小丁的家

分類: 🤖 AI 與自動化

  • Claude Code 配置升級完整指南：深度實踐版【含 5 場景、3 階段、4 案例、模板】

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？

    A: Skill 發現問題：

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
    • 4. 重新啟動 Claude Code
    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」

    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？

    A: Skill 發現問題：

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
    • 4. 重新啟動 Claude Code
    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」

    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`”timeout”: 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 – (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行

    • 結果：

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
    • ✅ 更新工作流時，只需修改一個 Skill 文件
    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）

    案例 3：代碼審查 – 從 CLAUDE.md 規則升級為 Custom Agent

    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
    • ⚡ 性能（N+1 查詢、unnecessary loops）
    • 🎨 風格和命名約定
    • ✅ 測試覆蓋率（至少 80%）
    • 🏗️ 架構一致性

    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：

    • ❌ 不同開發者得到的反饋風格不一致
    • ❌ 某些審查重點（安全性）被忽略
    • ❌ 後面的審查清單沒被仔細讀取（context decay）

    升級方案：Custom Agent

    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    使用方式：

    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    結果：

    • ✅ 所有 PR 都經過一致的高標準審查
    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
    • ✅ 開發者學到了項目特定的架構模式
    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
    • ✅ Tom 從審查工作中解放出來，可以專注開發

    案例 4：CI/CD 驗證 – 從 Stop Hook 中實現 99% 成功率

    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。

    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。

    診斷：

    • Step 1（數據收集）：90% 成功率
    • Step 2（驗證）：70% 成功率
    • Step 3（轉換）：75% 成功率
    • Step 4（加載）：80% 成功率
    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率

    解決方案：Stop Hook with Validator

    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    工作原理：

    1. Claude 編寫代碼（75% 成功率，假設）
    2. Claude 試圖停止
    3. Stop Hook 觸發，執行 3 個驗證器
    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
    5. Claude 修復代碼並重試（現在成功率 80%）
    6. 重複，直到所有驗證器通過

    數學計算：

    • 單次嘗試成功率：75%
    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%

    實際結果：

    • ✅ 數據管道成功率從 37.8% → 98%
    • ✅ 無需人工干預，自動迭代修復
    • ✅ Claude 在每次重試時學習錯誤模式
    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）

    決策樹：我應該用 Hook、Skill 還是 Agent？

    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    實踐行動清單（升級版）

    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：

    1. 今天：做一個簡單的 Hook
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
      • 用 PreToolUse Hook 實現它（複製上面的模板）
      • 測試它是否有效（5 分鐘）
    2. 本週：升級一個複雜工作流為 Skill
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
      • 提取完整步驟，建立 Skill 文件
      • 在 CLAUDE.md 中用一句話替代
      • 測試和驗證
    3. 本月：為一個關鍵角色建立 Custom Agent
      • 識別你重複執行的「角色」（審查員、測試員等）
      • 用上面的模板定義 Agent 配置
      • 啟動 Agent 並指派初始任務
      • 建立記憶庫追踪 Agent 學習的模式
    4. 持續：監控和迭代
      • 每週檢查 CLAUDE.md 是否 > 40 行
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
      • 收集 Agent 的反饋，改進指令
      • 更新記憶庫，讓 Agent 越來越聰明

    常見問題 & 故障排除

    Q: Hook 配置不生效，Claude 還是做了我不想要的事？

    A: 檢查清單：

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
    • 5. 測試：故意違反規則，看 Hook 是否觸發

    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？

    A: Skill 發現問題：

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
    • 4. 重新啟動 Claude Code
    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」

    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    步驟 3：啟動並指派任務給 Custom Agent

    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    步驟 4：驗收標準

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
    • ✅ 記憶庫能夠記住過往決策和模式
    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
    • ✅ 團隊成員可以信任 Agent 的專業判斷

    第三部分：真實案例深入剖析

    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據

    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。

    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。

    解決方案：PreToolUse Hook

    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。

    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考

    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。

    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。

    升級步驟：

  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行

    • 結果：

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
    • ✅ 更新工作流時，只需修改一個 Skill 文件
    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）

    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent

    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
    • ⚡ 性能（N+1 查詢、unnecessary loops）
    • 🎨 風格和命名約定
    • ✅ 測試覆蓋率（至少 80%）
    • 🏗️ 架構一致性

    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：

    • ❌ 不同開發者得到的反饋風格不一致
    • ❌ 某些審查重點（安全性）被忽略
    • ❌ 後面的審查清單沒被仔細讀取（context decay）

    升級方案：Custom Agent

    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    使用方式：

    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    結果：

    • ✅ 所有 PR 都經過一致的高標準審查
    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
    • ✅ 開發者學到了項目特定的架構模式
    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
    • ✅ Tom 從審查工作中解放出來，可以專注開發

    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率

    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。

    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。

    診斷：

    • Step 1（數據收集）：90% 成功率
    • Step 2（驗證）：70% 成功率
    • Step 3（轉換）：75% 成功率
    • Step 4（加載）：80% 成功率
    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率

    解決方案：Stop Hook with Validator

    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    工作原理：

    1. Claude 編寫代碼（75% 成功率，假設）
    2. Claude 試圖停止
    3. Stop Hook 觸發，執行 3 個驗證器
    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
    5. Claude 修復代碼並重試（現在成功率 80%）
    6. 重複，直到所有驗證器通過

    數學計算：

    • 單次嘗試成功率：75%
    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%

    實際結果：

    • ✅ 數據管道成功率從 37.8% → 98%
    • ✅ 無需人工干預，自動迭代修復
    • ✅ Claude 在每次重試時學習錯誤模式
    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）

    決策樹：我應該用 Hook、Skill 還是 Agent？

    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    實踐行動清單（升級版）

    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：

    1. 今天：做一個簡單的 Hook
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
      • 用 PreToolUse Hook 實現它（複製上面的模板）
      • 測試它是否有效（5 分鐘）
    2. 本週：升級一個複雜工作流為 Skill
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
      • 提取完整步驟，建立 Skill 文件
      • 在 CLAUDE.md 中用一句話替代
      • 測試和驗證
    3. 本月：為一個關鍵角色建立 Custom Agent
      • 識別你重複執行的「角色」（審查員、測試員等）
      • 用上面的模板定義 Agent 配置
      • 啟動 Agent 並指派初始任務
      • 建立記憶庫追踪 Agent 學習的模式
    4. 持續：監控和迭代
      • 每週檢查 CLAUDE.md 是否 > 40 行
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
      • 收集 Agent 的反饋，改進指令
      • 更新記憶庫，讓 Agent 越來越聰明

    常見問題 & 故障排除

    Q: Hook 配置不生效，Claude 還是做了我不想要的事？

    A: 檢查清單：

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
    • 5. 測試：故意違反規則，看 Hook 是否觸發

    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？

    A: Skill 發現問題：

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
    • 4. 重新啟動 Claude Code
    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」

    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    步驟 3：在 CLAUDE.md 中參考 Skill

    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。

    步驟 4：測試 Skill 是否有效

    1. 在對話中說：「/wordpress-blog-publisher」
    2. Claude 應該載入完整的 Skill 內容
    3. 按照 Skill 步驟發佈文章
    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）

    驗收標準：

    • ✅ Skill 在調用時完整載入
    • ✅ 文章成功發佈為草稿
    • ✅ SEO 和 AEO 結構化數據正確
    • ✅ CLAUDE.md 變得更精簡

    階段 3：CLAUDE.md → Custom Agent（最強大的升級）

    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。

    步驟 1：定義 Agent 的角色和責任

    角色 專長 工具存取 記憶庫
    代碼審查員 風格、安全性、性能、測試 Read、Grep、LSP 過去發現的模式和反模式
    測試工程師 單元測試、集成測試、驗收標準 Bash、Write、 Edit 專案測試策略和覆蓋率目標
    架構師 設計評審、技術決策、擴展性 Read、Agent、 WebFetch 系統架構決策和交易記錄
    DevOps 工程師 部署、基礎設施、監控、日誌 Bash、Kubectl、Docker 過往事件和根本原因分析

    步驟 2：建立 Custom Agent 配置

    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    步驟 3：啟動並指派任務給 Custom Agent

    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    步驟 4：驗收標準

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
    • ✅ 記憶庫能夠記住過往決策和模式
    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
    • ✅ 團隊成員可以信任 Agent 的專業判斷

    第三部分：真實案例深入剖析

    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據

    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。

    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。

    解決方案：PreToolUse Hook

    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。

    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考

    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。

    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。

    升級步驟：

  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行

    • 結果：

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
    • ✅ 更新工作流時，只需修改一個 Skill 文件
    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）

    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent

    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
    • ⚡ 性能（N+1 查詢、unnecessary loops）
    • 🎨 風格和命名約定
    • ✅ 測試覆蓋率（至少 80%）
    • 🏗️ 架構一致性

    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：

    • ❌ 不同開發者得到的反饋風格不一致
    • ❌ 某些審查重點（安全性）被忽略
    • ❌ 後面的審查清單沒被仔細讀取（context decay）

    升級方案：Custom Agent

    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    使用方式：

    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    結果：

    • ✅ 所有 PR 都經過一致的高標準審查
    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
    • ✅ 開發者學到了項目特定的架構模式
    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
    • ✅ Tom 從審查工作中解放出來，可以專注開發

    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率

    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。

    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。

    診斷：

    • Step 1（數據收集）：90% 成功率
    • Step 2（驗證）：70% 成功率
    • Step 3（轉換）：75% 成功率
    • Step 4（加載）：80% 成功率
    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率

    解決方案：Stop Hook with Validator

    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    工作原理：

    1. Claude 編寫代碼（75% 成功率，假設）
    2. Claude 試圖停止
    3. Stop Hook 觸發，執行 3 個驗證器
    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
    5. Claude 修復代碼並重試（現在成功率 80%）
    6. 重複，直到所有驗證器通過

    數學計算：

    • 單次嘗試成功率：75%
    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%

    實際結果：

    • ✅ 數據管道成功率從 37.8% → 98%
    • ✅ 無需人工干預，自動迭代修復
    • ✅ Claude 在每次重試時學習錯誤模式
    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）

    決策樹：我應該用 Hook、Skill 還是 Agent？

    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    實踐行動清單（升級版）

    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：

    1. 今天：做一個簡單的 Hook
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
      • 用 PreToolUse Hook 實現它（複製上面的模板）
      • 測試它是否有效（5 分鐘）
    2. 本週：升級一個複雜工作流為 Skill
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
      • 提取完整步驟，建立 Skill 文件
      • 在 CLAUDE.md 中用一句話替代
      • 測試和驗證
    3. 本月：為一個關鍵角色建立 Custom Agent
      • 識別你重複執行的「角色」（審查員、測試員等）
      • 用上面的模板定義 Agent 配置
      • 啟動 Agent 並指派初始任務
      • 建立記憶庫追踪 Agent 學習的模式
    4. 持續：監控和迭代
      • 每週檢查 CLAUDE.md 是否 > 40 行
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
      • 收集 Agent 的反饋，改進指令
      • 更新記憶庫，讓 Agent 越來越聰明

    常見問題 & 故障排除

    Q: Hook 配置不生效，Claude 還是做了我不想要的事？

    A: 檢查清單：

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
    • 5. 測試：故意違反規則，看 Hook 是否觸發

    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？

    A: Skill 發現問題：

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
    • 4. 重新啟動 Claude Code
    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」

    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？

    A: 調整 systemPrompt：

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
    • 2. 添加例子：「當你看到 X，應該做 Y」
    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
    • 4. 用具體案例測試新提示
    • 5. 逐步改進（每次改一個地方，測試）

    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？

    A: 設定合理的重試限制：

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
    • 3. 檢查 `successPattern` 的正則表達式是否正確
    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
    • 5. 測試驗證器：手動執行命令，確認它可以通過

    總結：5 個進化層級與 3 層升級的對應關係

    進化層級 你使用什麼 升級工具 特徵
    第 1 層：對話式 提示 無 每次都要告訴 Claude 做什麼
    第 2 層：配置式 CLAUDE.md 記錄規則 規則集中管理，但需要手動遵守
    第 3 層：自動化 Hook + Skill 強制執行 + 工作流編碼 規則自動化，工作流可重複使用
    第 4 層：編排式 Custom Agent 角色 + 工具 + 記憶 專職代理執行跨任務角色
    第 5 層：自主式 Agent 團隊 多個 Agent 協作與驗證 完全自主，人類監督

    最後的洞察：為什麼驗證器比工作流本身更重要

    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。

    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：

    • Step 1: 80% ✓
    • Step 2: 80% ✓
    • Step 3: 80% ✓
    • Step 4: 80% ✓
    • Step 5: 80% ✓
    • 整體成功率 = 0.8^5 = 32.8% ❌

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：

    • 第 1 次嘗試：70%
    • 第 2 次嘗試（修復失敗部分）：70%
    • 第 3 次嘗試：70%
    • 第 4 次嘗試：70%
    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅

    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。

    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。

    重點摘要（更新版）

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent

    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。

    重點摘要

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板

    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？

    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。

    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。

    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。

    Claude Code 協作的 5 個進化層級

    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：

    層級 特徵 工作流程 人工干預
    第 1 層：對話式 基礎對話 你輸入提示 → Claude 回應 → 你作出反應 每個步驟都需人工
    第 2 層：配置式 有指導原則 CLAUDE.md 引導行為，記憶保留學習成果 減少指導，保存教訓
    第 3 層：自動化 規則強制執行 Hooks 強制規則，Skills 編碼工作流 流程自動化，大幅減少
    第 4 層：編排式 專責代理 具備特定角色、工具與記憶的自訂 Agents 指派任務，代理自主執行
    第 5 層：自主式 團隊協作 Agent 團隊獨立運作並相互驗證成果 完全自主，人類監督

    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。

    第一部分：如何判斷何時升級？5 個具體場景

    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）

    症狀：

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
    • Claude 每週還是會誤讀 .env 或嘗試修改它
    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」

    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。

    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。

    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。

    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）

    症狀：

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
    • 你發現自己複製貼上同樣的指令給不同的專案

    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。

    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。

    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。

    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）

    症狀：

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」

    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。

    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。

    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。

    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）

    症狀：

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
    • 你懷疑 Claude 沒有充分「讀」後面的規則

    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。

    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。

    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。

    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）

    症狀：

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過

    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。

    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。

    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。

    第二部分：升級的 3 階段操作指南

    階段 1：CLAUDE.md → Hook（最簡單的升級）

    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。

    步驟 1：識別可升級為 Hook 的規則

    好的 Hook 候選規則具備這些特徵：

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
    • ✅ 是二元決定（做或不做，無灰色地帶）
    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）

    CLAUDE.md 中的例子：

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook

    步驟 2：決定使用哪種 Hook 類型

    Hook 類型 何時使用 例子
    PreToolUse 在工具執行前檢查並阻止 阻止 Read .env、Edit secrets.json
    PostToolUse 在工具執行後自動格式化或日誌 自動運行 prettier、記錄所有修改
    Stop 完成前驗證，失敗則迭代 驗證 JSON 有效性、測試通過率 > 95%

    步驟 3：在 settings.json 中配置 Hook

    模板：PreToolUse Hook（保護敏感檔案）

    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    













    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      • 

    











    想提升 Claude Code 工作效率？本文分享從台北 Claude 社群聚會的重要洞察，揭示如何從簡單的對話式協作升級到完全自動化的 AI 代理團隊。核心秘訣：從 CLAUDE.md 開始記錄規則，逐步升級到 Hooks、Skills 和自訂 Agents。一個月 10-30 個 PR、每行程式碼由 AI 撰寫的高效工作流，就從這裡開始。
    




    


    重點摘要
    



      

    • Claude Code 協作有 5 個進化層級：對話式 → 配置式 → 自動化 → 編排式 → 自主式
      • 

    • 大多數人卡在第 1-2 層，3 個關鍵路徑可升級：CLAUDE.md → Hook / Skill / 自訂 Agent
      • 

    • 核心發現：好驗證器搭配差工作流，勝過好工作流但沒驗證（關鍵理論基礎）
      • 

    • 實踐模式：每次 Claude 犯錯 → 加進 CLAUDE.md → 逐步升級到自動化規則
      • 

    • 典範案例：Boris Cherny 用 2500 token 的 CLAUDE.md 月合併 10-30 個 PR，100% AI 代碼
      • 

    • 新增：5 個升級判斷場景 + 3 層升級操作指南 + 4 個真實案例 + 可複製模板
      • 

    


    




    為什麼 Claude Code 配置從 CLAUDE.md 升級如此重要？
    




    在台北舉辦的 Claude 社群聚會中，軟體工程師 David Chu（前 ENS 團隊成員）分享了一個有趣的對比故事。他已經能同時跑著 3-5 個 Claude Code 實例，100% 的程式碼由 Claude 生成，每天合併 2-4 個 PR。但這套流程有個關鍵問題：每天下班時都精神疲憊，因為他得不斷切換終端機、審查輸出、重新下提示。
    




    相比之下，Claude Code 創作者 Boris Cherny 每天能合併 10-30 個 PR，一個月內完成 259 個 PR，每一行程式碼都由 Claude 撰寫。他的秘訣很簡單：「每次 Claude 做錯了什麼，就把它加進 CLAUDE.md，讓它永遠不再重蹈覆轍。」他的 CLAUDE.md 約有 2500 個 token，由整個團隊持續疊代。
    




    關鍵洞察來自 David 的觀察：開始時用 Boris 的方式（密集的 CLAUDE.md），培養習慣後，再逐步將成熟的規則從 CLAUDE.md 中「畢業」出去，升級為 Hooks、Skills 或自訂 Agents。
    




    Claude Code 協作的 5 個進化層級
    




    David 提出了一個完整的進化階梯，幫助理解 AI 代碼協作如何逐步自動化：
    




    


    
層級
特徵
工作流程
人工干預

    
    


    
第 1 層：對話式
基礎對話
你輸入提示 → Claude 回應 → 你作出反應
每個步驟都需人工

    

    
第 2 層：配置式
有指導原則
CLAUDE.md 引導行為，記憶保留學習成果
減少指導，保存教訓

    

    
第 3 層：自動化
規則強制執行
Hooks 強制規則，Skills 編碼工作流
流程自動化，大幅減少

    

    
第 4 層：編排式
專責代理
具備特定角色、工具與記憶的自訂 Agents
指派任務，代理自主執行

    

    
第 5 層：自主式
團隊協作
Agent 團隊獨立運作並相互驗證成果
完全自主，人類監督

    
    

    




    現實狀況：大多數人停留在第 1 或第 2 層。本文的目的，就是提供一個實踐指引，幫助你進階到第 3 或第 4 層。
    




    第一部分：如何判斷何時升級？5 個具體場景
    




    場景 1：你在 CLAUDE.md 中重複記錄同一條規則（升級信號：Go to Hook）
    




    症狀：
    




      

    • 你已經在 CLAUDE.md 寫過「不要修改 .env 檔」3 次
      • 

    • Claude 每週還是會誤讀 .env 或嘗試修改它
      • 

    • 你發現自己在 code review 中頻繁說「改回來，這不應該改」
      • 

    




    升級判斷：如果 Claude 在過去 2 週內違反同一條規則超過 3 次，→ 升級為 PreToolUse Hook。
    




    為什麼：文本警告（CLAUDE.md）對某些任務不夠有效。.env 檔案保護需要在工具層面強制執行，而不是在提示層面請求。
    




    案例：Tom 的 iDempiere 專案。他多次告訴 Claude 不要修改 `wordpress-config.env`，但 Claude 仍然在讀取和回顯敏感信息。升級為 PreToolUse Hook 後，Claude 根本無法執行 Read 工具在該檔案上——問題解決。
    




    場景 2：你創建了一套複雜但重複的工作流（升級信號：Go to Skill）
    




    症狀：
    




      

    • 每次做 WordPress 發佈時，你都要重複說「驗證 API → 發現類別 → SEO 優化 → 建立 JSON payload → 發佈」
      • 

    • CLAUDE.md 中已經有 800+ token 用於 WordPress 工作流說明
      • 

    • 你發現自己複製貼上同樣的指令給不同的專案
      • 

    




    升級判斷：如果一個工作流程的步驟數 > 5，且你每週執行它 > 2 次，→ 升級為 Skill。
    




    為什麼：Skill 只在需要時載入，不佔用基礎 context。CLAUDE.md 可以變成一行「使用 /wordpress-publish skill」，而詳細的工作流則藏在 Skill 定義中。
    




    案例：Tom 的 WordPress 發佈工作流（驗證 → 發現資源 → SEO → AEO 結構化數據 → Payload → 發佈）。這 6 步的流程現在是一個 Skill，CLAUDE.md 只說「發佈文章請用 /wordpress-publish skill」。
    




    場景 3：你需要 Claude 執行跨多個任務的相同角色（升級信號：Go to Custom Agent）
    




    症狀：
    




      

    • 你有一個「代碼審查員」的人設，涉及檢查風格、性能、安全性、測試覆蓋等
      • 

    • 這個人設需要在多個上下文中使用：PR 審查、重構驗證、新功能驗證
      • 

    • 你發現自己重複設定「作為高級工程師，檢查以下方面...」
      • 

    




    升級判斷：如果你為同一個「角色」建立了 3+ 個不同的 Skills 或重複定義相同的人設，→ 升級為 Custom Agent。
    




    為什麼：Custom Agent 將角色定義、工具存取權限和記憶綁定在一起。與其為代碼審查建 3 個不同的 Skills，不如建一個「審查員 Agent」，讓它在所有任務中保持一致的人設。
    




    案例：建立一個「品質保證 Agent」，具備：1) 風格檢查工具，2) 性能分析工具，3) 安全掃描工具，4) 測試驗證工具，5) 記憶庫（過去發現的常見問題）。它可以同時審查 PR、重構和新功能。
    




    場景 4：你的 CLAUDE.md 已經超過 50 行，且 Claude 開始無視某些規則（升級信號：整體升級）
    




    症狀：
    




      

    • CLAUDE.md 現在有 60+ 行，包含 15+ 條規則
      • 

    • 最後 5 條規則（第 11-15 項）被違反的頻率明顯更高
      • 

    • 你懷疑 Claude 沒有充分「讀」後面的規則
      • 

    




    升級判斷：當 CLAUDE.md > 50 行時，將後面 5-7 條規則分流到 Hooks/Skills/Agents。目標：讓 CLAUDE.md 回到 30-40 行的「黃金區間」。
    




    為什麼：上下文衰減。CLAUDE.md 越長，Claude 注意力越分散。將成熟規則升級出去，可以讓 CLAUDE.md 保持「高信噪比」。
    




    案例：Tom 的記憶系統。原本在 CLAUDE.md 中有 3 項記憶規則，但後來升級為 Hook（自動保存），現在 CLAUDE.md 只需提及記憶的存在位置。
    




    場景 5：某個工作流的成功率低於 80%（升級信號：Add Stop Hook with Validator）
    




    症狀：
    




      

    • 「生成 API 文檔」的工作流有 5 步，但只有 70% 機率全部成功
      • 

    • 每次都需要你手動檢查並要求 Claude 重做某些步驟
      • 

    • 你計算了一下，每個工作流平均需要 1.5 次嘗試才能通過
      • 

    




    升級判斷：如果工作流成功率 < 80% 且你每週執行 > 1 次，→ 添加 Stop Hook 並配備驗證器。
    




    為什麼：驗證器 + 迭代會指數級提高成功率。即使單步 70%，經過 Stop Hook 的驗證，整體成功率可以達到 99%。
    




    案例：API 文檔生成。加入 Stop Hook 驗證器後（檢查 OpenAPI 3.0 schema 有效性），成功率從 70% 躍升到 98%。Claude 自動重試並修正失敗之處。
    




    第二部分：升級的 3 階段操作指南
    




    階段 1：CLAUDE.md → Hook（最簡單的升級）
    




    目的：強制執行不會改變的規則（例如檔案保護、敏感信息防護）。
    




    步驟 1：識別可升級為 Hook 的規則
    




    好的 Hook 候選規則具備這些特徵：
    




      

    • ✅ 是一個「禁止」或「必須」規則（不是「建議」）
      • 

    • ✅ 涉及工具層面的操作（Read、Write、Edit、Bash）
      • 

    • ✅ 是二元決定（做或不做，無灰色地帶）
      • 

    • ✅ 違反它會造成實質傷害（安全、隱私、資料丟失）
      • 

    




    CLAUDE.md 中的例子：
    




      

    • ❌ 「避免 over-engineering」→ 太模糊，不適合 Hook
      • 

    • ✅ 「絕不修改 .env 檔案」→ 清晰、二元，適合 Hook
      • 

    • ✅ 「不提交包含 console.log() 的代碼」→ 可驗證，適合 Stop Hook
      • 

    




    步驟 2：決定使用哪種 Hook 類型
    




    


    
Hook 類型
何時使用
例子

    
    


    
PreToolUse
在工具執行前檢查並阻止
阻止 Read .env、Edit secrets.json

    

    
PostToolUse
在工具執行後自動格式化或日誌
自動運行 prettier、記錄所有修改

    

    
Stop
完成前驗證，失敗則迭代
驗證 JSON 有效性、測試通過率 > 95%

    
    

    




    步驟 3：在 settings.json 中配置 Hook
    




    模板：PreToolUse Hook（保護敏感檔案）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "description": "Prevent reading .env files",
        "toolName": "Read",
        "condition": "filename contains '.env' OR filename contains 'secrets' OR filename contains 'credentials'",
        "action": "block",
        "message": "❌ Cannot read .env or secrets files. Use environment variables instead."
      },
      {
        "description": "Warn before editing production config",
        "toolName": "Edit",
        "condition": "filename contains 'production.json' OR filename contains 'config.prod'",
        "action": "confirm",
        "message": "⚠️ About to edit production config. Are you sure? (yes/no)"
      }
    ]
  }
}




    模板：Stop Hook with Validator（驗證 JSON 有效性）
    




    // ~/.claude/settings.json
{
  "hooks": {
    "stop": [
      {
        "description": "Validate JSON before stopping",
        "condition": "task type is 'create JSON' OR output contains '.json'",
        "validator": {
          "command": "jq empty",
          "input": "last_output",
          "allowRetry": true,
          "maxRetries": 3,
          "retryMessage": "JSON validation failed. Fixing syntax errors..."
        }
      },
      {
        "description": "Ensure all tests pass before stopping",
        "condition": "task involves 'testing' OR 'test' in output",
        "validator": {
          "command": "npm test 2>&1 | grep -c 'passed'",
          "successPattern": "[0-9]+ passed",
          "allowRetry": true,
          "maxRetries": 2,
          "retryMessage": "Tests failed. Reviewing and fixing failures..."
        }
      }
    ]
  }
}

    




    步驟 4：測試 Hook 是否有效
    




      

    1. 重新啟動 Claude Code（hooks 在啟動時載入）
      2. 

    2. 故意嘗試觸發 Hook（例如，要求 Claude 讀取 .env）
      3. 

    3. 驗證 Hook 是否成功阻止或警告
      4. 

    4. 檢查日誌：`~/.claude/logs/hooks.log`
      5. 

    




    驗收標準：
    




      

    • ✅ 敏感檔案無法被讀取
      • 

    • ✅ Claude 主動回報被阻止的操作
      • 

    • ✅ 沒有拋出例外或崩潰
      • 

    




    階段 2：CLAUDE.md → Skill（最有影響力的升級）
    




    目的：將複雜工作流編碼為可重複使用的 Skill，只在需要時載入。
    




    步驟 1：提取工作流的完整步驟
    




    拿出你的 CLAUDE.md，找到某個工作流（例如 WordPress 發佈）。列出完整的步驟序列：
    




      

    1. 驗證 API 憑證是否有效
      2. 

    2. 發現可用的類別和標籤
      3. 

    3. 根據用戶內容進行 SEO 優化
      4. 

    4. 生成 FAQ 和 Article 結構化數據（AEO）
      5. 

    5. 建立 JSON payload
      6. 

    6. POST 到 WordPress REST API（草稿狀態）
      7. 

    7. 如果是系列文章，更新交叉連結
      8. 

    8. 報告最終 URL 給用戶
      9. 

    




    步驟 2：在 ~/.claude/skills/ 中建立 Skill 文件
    




    // 文件：~/.claude/skills/wordpress-blog-publisher.md

---
name: wordpress-blog-publisher
description: Publish SEO and AEO optimized articles to WordPress via REST API
tags: [wordpress, blogging, content-management, seo, aeo]
trigger_patterns:
  - "post to blog"
  - "write blog article"
  - "publish to wordpress"
---

# WordPress Blog Publisher Skill

## Overview
Publish SEO-optimized and AEO (Answer Engine Optimization)-ready articles to WordPress via REST API.

## Workflow

### Step 1: Verify API Access
Load WordPress credentials from ~/.claude/projects/-home-tom/wordpress-config.env
Test access with: `curl -s -o /dev/null -w "%{http_code}" -u "USER:PASS" "SITE/wp-json/wp/v2/posts?per_page=1"`
Expected response: 200

### Step 2: Discover Resources
- List categories: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/categories"`
- List tags: `curl -s -u "USER:PASS" "SITE/wp-json/wp/v2/tags"`
- Match user's content to appropriate categories

### Step 3: SEO Optimization Checklist
- Title: Under 60 chars, primary keyword near front
- Slug: Short, keyword-rich, no stop words
- Excerpt: 120-155 chars, includes primary keyword
- H2 headings: 4-8 per article, each with secondary keywords
- First 100 words: Must contain primary keyword naturally
- Internal links: Link to 2-3 related posts
- Word count: 1,500-3,000 words

### Step 4: AEO (Answer Engine Optimization)
Add FAQ Schema and Article Schema JSON-LD:

\`\`\`html



\`\`\`

### Step 5: Create JSON Payload
All content must use WordPress Gutenberg block format ( etc.)

Template:
\`\`\`json
{
  "title": "SEO Title (under 60 chars)",
  "slug": "keyword-rich-slug",
  "excerpt": "Meta description 120-155 chars with primary keyword",
  "content": "\n
    Content here
    ",
  "status": "draft",
  "categories": [ID],
  "tags": [ID1, ID2]
}
\`\`\`

### Step 6: Publish to WordPress
\`\`\`bash
curl -X POST \
  -u "USER:PASS" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "SITE/wp-json/wp/v2/posts"
\`\`\`

### Step 7: Report URL to User
Extract post ID from response, construct final URL:
https://blog.domain.com/YYYY/MM/DD/slug/

## Important Notes
- Always publish as "draft" first, never directly to "publish"
- Validate JSON before submitting
- Include both FAQ and Article schemas
- Use proper WordPress block format

    




    步驟 3：在 CLAUDE.md 中參考 Skill
    




    // CLAUDE.md - 簡化至一行

## 發佈文章
使用 /wordpress-blog-publisher skill 發佈內容到 WordPress。該 skill 自動處理驗證、SEO、AEO、API 呼叫。

    




    從 CLAUDE.md 中移除 800+ token 的 WordPress 工作流詳細說明。
    




    步驟 4：測試 Skill 是否有效
    




      

    1. 在對話中說：「/wordpress-blog-publisher」
      2. 

    2. Claude 應該載入完整的 Skill 內容
      3. 

    3. 按照 Skill 步驟發佈文章
      4. 

    4. 驗證發佈成功（檢查 WordPress 後台或 API 回應）
      5. 

    




    驗收標準：
    




      

    • ✅ Skill 在調用時完整載入
      • 

    • ✅ 文章成功發佈為草稿
      • 

    • ✅ SEO 和 AEO 結構化數據正確
      • 

    • ✅ CLAUDE.md 變得更精簡
      • 

    




    階段 3：CLAUDE.md → Custom Agent（最強大的升級）
    




    目的：為特定角色（例如代碼審查員、測試工程師、架構師）定義獨立的 AI 代理，具備專屬工具和記憶。
    




    步驟 1：定義 Agent 的角色和責任
    




    


    
角色
專長
工具存取
記憶庫

    
    


    
代碼審查員
風格、安全性、性能、測試
Read、Grep、LSP
過去發現的模式和反模式

    

    
測試工程師
單元測試、集成測試、驗收標準
Bash、Write、 Edit
專案測試策略和覆蓋率目標

    

    
架構師
設計評審、技術決策、擴展性
Read、Agent、 WebFetch
系統架構決策和交易記錄

    

    
DevOps 工程師
部署、基礎設施、監控、日誌
Bash、Kubectl、Docker
過往事件和根本原因分析

    
    

    




    步驟 2：建立 Custom Agent 配置
    




    // 文件：~/.claude/agents/code-reviewer.json

{
  "name": "code-reviewer",
  "description": "Senior code reviewer - checks style, security, performance, and tests",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer with 10+ years of experience. Your job is to:

1. **Style & Standards**: Check code follows project conventions (naming, formatting, structure)
2. **Security**: Identify potential vulnerabilities (SQL injection, XSS, unsafe crypto, privilege escalation)
3. **Performance**: Flag inefficient algorithms, N+1 queries, unnecessary iterations
4. **Testing**: Verify adequate test coverage and that edge cases are tested
5. **Architecture**: Ensure changes align with system design and don't introduce tight coupling

## Your Review Process:
- Read the entire context (files, previous PRs, architecture docs)
- Ask clarifying questions before criticizing
- Explain the "why" not just the "what"
- Suggest concrete improvements with code examples
- Rate severity: Critical (security/data loss) vs Major vs Minor

## Key Rules:
- Be constructive and respectful in tone
- Acknowledge good practices when you see them
- Never approve without understanding the change
- Flag assumptions and ask for validation
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch"],
    "denied": ["Write", "Edit", "Bash", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-memory/",
    "categories": [
      "security-patterns",
      "performance-antipatterns",
      "project-conventions",
      "past-mistakes"
    ]
  },
  "permissions": {
    "canAccessRemoteRepos": true,
    "canViewPullRequests": true,
    "requiresApprovalFor": ["suggesting-major-refactors"]
  }
}

    




    步驟 3：啟動並指派任務給 Custom Agent
    




    // 在 Claude Code 中

// 啟動代碼審查員 Agent
/spawn agent=code-reviewer

// 指派審查任務
@code-reviewer Please review the PR for my database migration module. 
Check for: SQL injection risks, performance (this handles 10k+ records), 
test coverage, and alignment with our ORM patterns.

// Agent 會自動：
// 1. 讀取相關文件
// 2. 查閱過往審查記錄（記憶庫）
// 3. 進行深度分析
// 4. 提供詳細反饋

    




    步驟 4：驗收標準
    




      

    • ✅ Agent 在其專業領域內提供一致、高質量的反饋
      • 

    • ✅ 記憶庫能夠記住過往決策和模式
      • 

    • ✅ 即使跨多個 PR 或項目，Agent 的風格和標準保持一致
      • 

    • ✅ 團隊成員可以信任 Agent 的專業判斷
      • 

    




    第三部分：真實案例深入剖析
    




    案例 1：Tom 的 iDempiere 專案 - 從 Hook 中拯救敏感數據
    




    背景：Tom 正在開發 iDempiere ERP 系統的增強模塊。他的開發環境配置了多個 API 憑證（WordPress、iDempiere REST API、數據庫密碼），都存儲在 ~/.claude/projects/-home-tom/wordpress-config.env。
    




    問題：Claude 很有幫助，但有時會主動建議「讓我檢查 .env 文件確保格式正確」，然後就會讀取並回顯敏感信息。即使 Tom 多次在 CLAUDE.md 中寫「不要讀取 .env」，問題仍然偶爾發生。
    




    解決方案：PreToolUse Hook
    




    // settings.json 中的 Hook 配置

{
  "hooks": {
    "preToolUse": [
      {
        "id": "protect-env-files",
        "description": "Block reading any .env, secrets, or credential files",
        "toolName": "Read",
        "condition": "filename.endsWith('.env') || filename.includes('secrets') || filename.includes('credentials') || filename.includes('config.env')",
        "action": "block",
        "message": "❌ Cannot read .env files or sensitive configuration. These contain API keys and passwords.\n\nIf you need to use an API, ask the user for the specific value you need, or use the 'source' command to load it into the environment.",
        "logToFile": "~/.claude/logs/security-blocks.log"
      }
    ]
  }
}

    




    結果：Claude 無法再讀取 .env 文件。當它嘗試時，Hook 會自動阻止並提示：「無法讀取 .env 文件」。Claude 學會了改為詢問「你能告訴我 WORDPRESS_APP_PASSWORD 是什麼嗎？」（使用者自行決定是否透露）。安全漏洞完全消除。
    




    案例 2：WordPress 博客發佈 - 從 800 token 工作流變成 10 行 Skill 參考
    




    背景：Tom 有一個常見需求：發佈優化後的博客文章到 WordPress。這個工作流包括：驗證 API → 發現類別標籤 → SEO 優化 → 生成 FAQ 和 Article Schema → 建立 JSON payload → 發佈 → 交叉連結（如果是系列）。
    




    問題：CLAUDE.md 中有 800+ token 用於這個工作流的詳細說明。每次 Tom 要求新發佈時，都要重複指定同樣的步驟。另外，Tom 新建立的其他專案（Analytics、Stock-Verify）也需要相同的工作流。
    




    升級步驟：
    




  • 從 CLAUDE.md 提取完整的工作流（8 個詳細步驟）
    • 

  • 在 ~/.claude/skills/wordpress-blog-publisher.md 中建立 Skill 文件
    • 

  • Skill 包含：前置條件（API 驗證）、完整工作流、SEO 檢查清單、AEO 結構化數據模板、WordPress REST API 命令
    • 

  • 在 CLAUDE.md 中替換為一句：「發佈文章時使用 /wordpress-blog-publisher skill」
    • 

  • 測試：說 /wordpress-blog-publisher，驗證 Skill 完整載入並正確運行
    • 




    結果：
    




      

    • ✅ CLAUDE.md 從 150 行減到 130 行（節省 800+ token）
      • 

    • ✅ WordPress 發佈現在只需一句：「/wordpress-blog-publisher」
      • 

    • ✅ 相同的 Skill 可在 3 個不同專案中重複使用
      • 

    • ✅ 更新工作流時，只需修改一個 Skill 文件
      • 

    • ✅ 實際成果：Tom 第一次發佈擴展版文章時，成功率 95%（比之前的手動 70% 提高了）
      • 

    




    案例 3：代碼審查 - 從 CLAUDE.md 規則升級為 Custom Agent
    




    背景：Tom 的團隊有 4 個開發者。他希望每個 PR 都經過一致的代碼審查，檢查項目包括：
    




      

    • 🔒 安全性（SQL injection、XSS、privilege escalation）
      • 

    • ⚡ 性能（N+1 查詢、unnecessary loops）
      • 

    • 🎨 風格和命名約定
      • 

    • ✅ 測試覆蓋率（至少 80%）
      • 

    • 🏗️ 架構一致性
      • 

    




    初始方法（失敗）：Tom 在 CLAUDE.md 中寫了一份 600 token 的審查清單。結果很糟：
    




      

    • ❌ 不同開發者得到的反饋風格不一致
      • 

    • ❌ 某些審查重點（安全性）被忽略
      • 

    • ❌ 後面的審查清單沒被仔細讀取（context decay）
      • 

    




    升級方案：Custom Agent
    




    // ~/.claude/agents/code-reviewer-tom-projects.json

{
  "name": "code-reviewer-tom",
  "description": "Dedicated code reviewer for Tom's iDempiere and Analytics projects",
  "model": "claude-opus-4-6",
  "systemPrompt": `You are a senior code reviewer for Tom's open-source projects (iDempiere modules, Analytics, Stock-Verify).

## Your Standards:
1. **Security** (CRITICAL): Check for SQL injection, XSS, credential leaks, unsafe deserialization, privilege escalation
2. **Performance**: Flag N+1 queries, unnecessary iterations, inefficient algorithms. Target: O(n) not O(n²)
3. **Tests**: Require 80%+ code coverage. Check for edge cases and error handling.
4. **Style**: Follow project conventions:
   - Java: iDempiere package patterns, no static abuse
   - Python: PEP8, type hints for complex functions
   - SQL: Use prepared statements, clear table aliases
5. **Architecture**: Ensure changes don't break service boundaries or introduce tight coupling

## Tone:
- Be encouraging ("Good approach here because...")
- Ask "Why?" before criticizing
- Suggest concrete improvements with code examples
- Severity levels: 🔴 Critical (fix before merge) | 🟡 Major (should fix) | 🔵 Minor (nice to have)

## Tom's Specific Rules (from his projects):
- iDempiere: No hardcoded reference IDs, use AD_Column lookups
- WordPress: Never modify .env, use config injection
- Analytics: Data pipelines must be idempotent, validate after each stage
`,
  "tools": {
    "allowed": ["Read", "Grep", "LSP", "WebFetch", "Bash"],
    "denied": ["Write", "Edit", "Agent"]
  },
  "memory": {
    "enabled": true,
    "location": "~/.claude/agents/code-reviewer-tom-memory/",
    "trackingCategories": {
      "security-findings": "Past security issues found and how they were fixed",
      "performance-patterns": "Common performance issues in Tom's codebase",
      "architectural-decisions": "Why certain patterns were chosen, anti-patterns to avoid",
      "project-conventions": "Specific style and architecture rules for each project"
    }
  },
  "approvalRules": {
    "requiresUserApprovalBefore": ["suggesting major refactors", "marking as 🔴 Critical"],
    "canAutoApproveFor": ["minor formatting", "documentation improvements"]
  }
}

    




    使用方式：
    




    // 在 PR 中

@code-reviewer-tom Please review this PR for my Analytics data pipeline module.
Focus on: data validation, idempotency, and test coverage.

// Agent 會自動：
// 1. 使用獨立的 opus 模型（更強大）
// 2. 參考記憶庫中過往的安全發現和架構決策
// 3. 應用 Tom 的具體規則（例如 iDempiere pattern）
// 4. 提供一致、高質量的反饋
// 5. 學習新的模式並更新記憶庫

    




    結果：
    




      

    • ✅ 所有 PR 都經過一致的高標準審查
      • 

    • ✅ 安全性發現增加了 60%（Agent 不會因為累而忽略）
      • 

    • ✅ 開發者學到了項目特定的架構模式
      • 

    • ✅ Agent 的記憶庫逐漸積累项目知識，未來的审查更聰明
      • 

    • ✅ Tom 從審查工作中解放出來，可以專注開發
      • 

    




    案例 4：CI/CD 驗證 - 從 Stop Hook 中實現 99% 成功率
    




    背景：Tom 的 Analytics 專案有一個複雜的數據管道：收集 → 驗證 → 轉換 → 加載。每個步驟都有驗證邏輯，但經常有某個環節失敗。
    




    問題：Claude 編寫的數據管道代碼成功率約 65%（3 次嘗試中 2 次失敗）。失敗原因多樣：JSON 格式、timestamp 解析、null 處理等。每次失敗都需要人工介入。
    




    診斷：
    




      

    • Step 1（數據收集）：90% 成功率
      • 

    • Step 2（驗證）：70% 成功率
      • 

    • Step 3（轉換）：75% 成功率
      • 

    • Step 4（加載）：80% 成功率
      • 

    • 整體 = 0.9 × 0.7 × 0.75 × 0.8 = 37.8% 成功率
      • 

    




    解決方案：Stop Hook with Validator
    




    // settings.json

{
  "hooks": {
    "stop": [
      {
        "id": "validate-data-pipeline",
        "description": "Validate analytics data pipeline before stopping",
        "condition": "task involves 'data pipeline' OR 'ETL' OR 'collect' in description",
        "validators": [
          {
            "name": "json-validity",
            "command": "python -m json.tool /tmp/output.json > /dev/null 2>&1 && echo OK || (echo 'JSON Error' && exit 1)",
            "successPattern": "OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "JSON validation failed. Check the output format and fix any syntax errors."
          },
          {
            "name": "schema-compliance",
            "command": "python << 'EOF'\nimport json\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\nassert all(k in data for k in ['id', 'timestamp', 'value']), 'Missing required fields'\nassert len(data['id']) > 0, 'ID cannot be empty'\nprint('Schema OK')\nEOF",
            "successPattern": "Schema OK",
            "failureAction": "retry",
            "maxRetries": 2,
            "retryPrompt": "Schema validation failed. Ensure all required fields are present."
          },
          {
            "name": "date-parsing",
            "command": "python << 'EOF'\nfrom datetime import datetime\nwith open('/tmp/output.json') as f:\n  data = json.load(f)\ntry:\n  datetime.fromisoformat(data['timestamp'])\n  print('Date OK')\nexcept:\n  raise ValueError('Invalid timestamp format')\nEOF",
            "successPattern": "Date OK",
            "failureAction": "retry",
            "maxRetries": 1,
            "retryPrompt": "Timestamp parsing failed. Use ISO 8601 format (YYYY-MM-DDTHH:MM:SS)."
          }
        ]
      }
    ]
  }
}

    




    工作原理：
    




      

    1. Claude 編寫代碼（75% 成功率，假設）
      2. 

    2. Claude 試圖停止
      3. 

    3. Stop Hook 觸發，執行 3 個驗證器
      4. 

    4. 如果失敗，Hook 阻止停止，並告訴 Claude 問題在哪
      5. 

    5. Claude 修復代碼並重試（現在成功率 80%）
      6. 

    6. 重複，直到所有驗證器通過
      7. 

    




    數學計算：
    




      

    • 單次嘗試成功率：75%
      • 

    • 3 次迭代的成功率：1 - (0.25)³ = 1 - 0.0156 = 98.4%
      • 

    




    實際結果：
    




      

    • ✅ 數據管道成功率從 37.8% → 98%
      • 

    • ✅ 無需人工干預，自動迭代修復
      • 

    • ✅ Claude 在每次重試時學習錯誤模式
      • 

    • ✅ 開發速度提高 3 倍（因為不用等待失敗再修復）
      • 

    




    決策樹：我應該用 Hook、Skill 還是 Agent？
    




    問題：我有一套 Claude 應該遵循的規則/流程，該升級嗎？

├─ 它是「不要做X」嗎？
│  ├─ YES → Hook (PreToolUse)
│  │   例：「不要修改 .env」→ PreToolUse Hook
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它涉及 5+ 個步驟且每週 > 1 次？
│  ├─ YES → Skill
│  │   例：WordPress 發佈工作流（8 步）→ Skill
│  │
│  └─ NO → 轉向下一個問題
│
├─ 它是一個「角色」，涉及多個不同任務？
│  ├─ YES → Custom Agent
│  │   例：「代碼審查員」→ Custom Agent
│  │
│  └─ NO → 保留在 CLAUDE.md
│
└─ 成功率 < 80% 且每週 > 1 次？
   ├─ YES → Stop Hook with Validator
   │   例：數據管道成功率 75% → Stop Hook
   │
   └─ NO → 保留在 CLAUDE.md，監控

結論：
- Hook: 保護性規則，一句話就能說清楚
- Skill: 工作流自動化，經常重複執行
- Agent: 角色定義，跨多個不同任務
- Stop Hook: 質量把關，自動迭代修復

    




    實踐行動清單（升級版）
    




    現在你知道了理論、操作方法和實際案例。以下是可以立即行動的步驟：
    




      

    1. 今天：做一個簡單的 Hook
   
        
   
      • 選擇一個安全敏感的規則（例如「保護敏感檔案」）
        • 
   
      • 用 PreToolUse Hook 實現它（複製上面的模板）
        • 
   
      • 測試它是否有效（5 分鐘）
        • 
   
      

      2. 

    2. 本週：升級一個複雜工作流為 Skill
   
        
   
      • 找到 CLAUDE.md 中最長的工作流描述（> 400 token）
        • 
   
      • 提取完整步驟，建立 Skill 文件
        • 
   
      • 在 CLAUDE.md 中用一句話替代
        • 
   
      • 測試和驗證
        • 
   
      

      3. 

    3. 本月：為一個關鍵角色建立 Custom Agent
   
        
   
      • 識別你重複執行的「角色」（審查員、測試員等）
        • 
   
      • 用上面的模板定義 Agent 配置
        • 
   
      • 啟動 Agent 並指派初始任務
        • 
   
      • 建立記憶庫追踪 Agent 學習的模式
        • 
   
      

      4. 

    4. 持續：監控和迭代
   
        
   
      • 每週檢查 CLAUDE.md 是否 > 40 行
        • 
   
      • 追踪違反規則的頻率，不遵守的 → 升級為 Hook
        • 
   
      • 收集 Agent 的反饋，改進指令
        • 
   
      • 更新記憶庫，讓 Agent 越來越聰明
        • 
   
      

      5. 

    




    常見問題 & 故障排除
    




    Q: Hook 配置不生效，Claude 還是做了我不想要的事？
    




    A: 檢查清單：
    




      

    • 1. 重新啟動 Claude Code（Hook 在啟動時載入）
      • 

    • 2. 檢查 settings.json 的 JSON 有效性：`jq . ~/.claude/settings.json`
      • 

    • 3. 驗證 condition 邏輯是否正確（使用 shell glob patterns）
      • 

    • 4. 查看 Hook 日誌：`tail ~/.claude/logs/hooks.log`
      • 

    • 5. 測試：故意違反規則，看 Hook 是否觸發
      • 

    




    Q: Skill 文件建立好了，但 Claude 說「我不知道這個 skill」？
    




    A: Skill 發現問題：
    




      

    • 1. 確保檔案位置正確：`~/.claude/skills/your-skill-name.md`
      • 

    • 2. 檢查檔案開頭的 frontmatter（name、description、trigger_patterns）
      • 

    • 3. 檢查檔案名和 frontmatter 中的 name 是否一致
      • 

    • 4. 重新啟動 Claude Code
      • 

    • 5. 在對話中明確說：「/your-skill-name」或「使用 your-skill-name」
      • 

    




    Q: Custom Agent 建立了，但它的回應方式跟我期待的不一樣？
    




    A: 調整 systemPrompt：
    




      

    • 1. 編輯 agent JSON，調整 systemPrompt（更清晰、更具體）
      • 

    • 2. 添加例子：「當你看到 X，應該做 Y」
      • 

    • 3. 定義你希望的輸出格式（結構化、馬克福恩等）
      • 

    • 4. 用具體案例測試新提示
      • 

    • 5. 逐步改進（每次改一個地方，測試）
      • 

    




    Q: Stop Hook 的驗證器失敗，Claude 一直在重試，永遠停不下來？
    




    A: 設定合理的重試限制：
    




      

    • 1. 確保 `maxRetries` 有上限（例如 3 次）
      • 

    • 2. 驗證邏輯是否可達成（太嚴格的規則 → 永遠失敗）
      • 

    • 3. 檢查 `successPattern` 的正則表達式是否正確
      • 

    • 4. 添加 timeout：`"timeout": 30000` （毫秒）
      • 

    • 5. 測試驗證器：手動執行命令，確認它可以通過
      • 

    




    總結：5 個進化層級與 3 層升級的對應關係
    




    


    
進化層級
你使用什麼
升級工具
特徵

    
    


    
第 1 層：對話式
提示
無
每次都要告訴 Claude 做什麼

    

    
第 2 層：配置式
CLAUDE.md
記錄規則
規則集中管理，但需要手動遵守

    

    
第 3 層：自動化
Hook + Skill
強制執行 + 工作流編碼
規則自動化，工作流可重複使用

    

    
第 4 層：編排式
Custom Agent
角色 + 工具 + 記憶
專職代理執行跨任務角色

    

    
第 5 層：自主式
Agent 團隊
多個 Agent 協作與驗證
完全自主，人類監督

    
    

    




    最後的洞察：為什麼驗證器比工作流本身更重要
    




    David 在分享中強調了一個易被忽視但極其深刻的原理：在一個多步驟的工作流中，驗證器的威力遠超好的工作流本身。
    




    為什麼？因為可靠性是複合的。假設你有 5 個步驟，每個成功率 80%：
    




      

    • Step 1: 80% ✓
      • 

    • Step 2: 80% ✓
      • 

    • Step 3: 80% ✓
      • 

    • Step 4: 80% ✓
      • 

    • Step 5: 80% ✓
      • 

    • 整體成功率 = 0.8^5 = 32.8% ❌
      • 

    




    但如果你在末尾加一個 Stop Hook 驗證器，即使單步成功率只有 70%，經過迭代：
    




      

    • 第 1 次嘗試：70%
      • 

    • 第 2 次嘗試（修復失敗部分）：70%
      • 

    • 第 3 次嘗試：70%
      • 

    • 第 4 次嘗試：70%
      • 

    • 4 次迭代後成功率 = 1 - (0.3)^4 = 99.19% ✅
      • 

    




    這意味著：一個「差」的工作流（70% 單步成功率）搭配驗證器，比一個「好」的工作流（80% 單步）但沒驗證器更可靠 99 倍。
    




    这就是为什么 Boris Cherny 能达到月 10-30 个 PR 的效率。他不是拥有完美的工作流，而是拥有完美的验证器。
    




    重點摘要（更新版）
    




      

    • ✅ 判斷升級的 5 個場景：規則違反、工作流複雜度、角色跨任務、CLAUDE.md 過長、成功率低
      • 

    • ✅ 3 階段升級指南：Hook（最簡單）→ Skill（最有影響）→ Custom Agent（最強大）
      • 

    • ✅ 4 個真實案例：敏感檔案保護、WordPress 發佈、代碼審查、CI/CD 驗證
      • 

    • ✅ 決策樹：根據你的規則/流程特性，決定用 Hook/Skill/Agent
      • 

    • ✅ 驗證器的魔力：好驗證器 + 差工作流 > 好工作流 + 無驗證
      • 

    • ✅ 立即行動：今天做一個 Hook，本週升級一個 Skill，本月建立一個 Agent
      •

  • 【實戰指南】如何為 AI 代理準備資料？Agent Spec 設計指南 — 從 SDD 到代理規格書的完整轉化

    在上兩篇文章中，我們解析了《2026 Agentic Coding Trends Report》的 8 大趨勢，也實際跑了一次雙代理流水線。但實戰中最常被問到的問題是：「我到底要準備什麼資料給 AI 代理？」

    答案不是傳統的 SDD（Software Design Document）。50 頁的 Word 文件會讓代理 timeout。你需要的是一種為 AI 代理設計的輕量規格書——Agent Spec。

    一、為什麼 SDD 不適合代理？

    傳統 SDD（給人看的） Agent Spec（給 AI 看的）
    長度 50+ 頁 200 行以內
    包含 背景、歷史、會議記錄、UML 圖 只有「做什麼」「不做什麼」「怎樣算完成」
    表達方式 文字描述 + 圖表 程式碼範例 + 簽名契約
    閱讀方式 多人在不同時間反覆閱讀 一個代理在一次 context 中完整消化
    設計原則 越詳細越好 越精準越好（長度是敵人）

    核心差異：SDD 追求完整性，Agent Spec 追求精準性。代理不需要知道「為什麼要做這個功能」的三頁背景故事，它需要知道「輸入什麼、輸出什麼、邊界怎麼處理」。

    二、Agent Spec 的五個區塊

    一份文件，五個區塊，控制在 200 行以內。以下用「訂單處理功能」為例完整示範：

    區塊一：WHAT — 做什麼（必要）

    這是最核心的區塊。不要寫散文，直接給輸入輸出契約：

    ## 功能規格

### 輸入輸出契約（最重要的部分）
- 函數簽名：`def process_order(order: Order) -> Receipt`
- 輸入範例：
  {"item_id": "A001", "qty": 3, "user_id": "U100"}
- 輸出範例：
  {"receipt_id": "R001", "total": 150.0, "status": "confirmed"}
- 錯誤回傳：
  raises InsufficientStockError when qty > available
  raises DuplicateOrderError when same order within 1 second

### 行為規則
1. 庫存不足時拒絕訂單，不要部分出貨
2. 同一用戶同一秒內的重複訂單要去重
3. 金額計算精度到小數點後 2 位

    為什麼這樣寫有效？因為代理最擅長的是「根據契約實作」。函數簽名 + 輸入輸出範例 + 邊界條件 = 代理需要的全部資訊。業務背景、產品需求文件、PM 的原始 ticket——這些人類需要，代理不需要。

    區塊二：HOW — 技術約束（必要）

    告訴代理已經有什麼可以直接用。這是最容易被忽略、但最能提升品質的資訊：

    ## 技術約束

### 必須使用
- 語言：Python 3.11
- 框架：FastAPI
- 資料庫：已有的 PostgreSQL，用 SQLAlchemy ORM
- 現有模組：from app.models import Order, Product（已存在，直接用）

### 現有介面（可以直接呼叫的）
- db.session.get(Product, product_id) -> 查商品
- db.session.add(receipt) -> 寫入收據
- redis_client.get(f"order:{user_id}:{hash}") -> 去重檢查
- from app.services.product_service import get_price -> 取得商品價格

### 專案結構（讓代理知道檔案放哪裡）
src/
  models/order.py       -- 資料模型（已存在）
  services/             -- 業務邏輯放這裡
  routes/orders.py      -- API 路由（要在這裡加 endpoint）

    為什麼這麼重要？沒有這個區塊，代理會自己發明資料庫連接方式、自己建立 model class、自己設計專案結構——然後跟你的現有程式碼完全不相容。告訴它「已經有什麼」，它就會「用已經有的」。

    區塊三：DON’T — 禁止事項（必要）

    從我們的雙代理實驗中學到的最重要教訓：禁止比允許更重要。AI 的創造空間是無限的，你無法列舉所有「應該做」的事，但你可以明確劃定「絕對不能做」的紅線。

    ## 禁止

### 絕對不可（違反 = 程式碼作廢）
- 不可直接寫 SQL（必須用 ORM）
- 不可在 API handler 裡寫業務邏輯（必須放 service 層）
- 不可 catch 所有 Exception（必須指定具體類型）
- 不可新增資料表（只能用現有的 schema）
- 不可使用 global 變數

### 不要（違反 = 需要修改）
- 不要新增依賴套件
- 不要修改現有的 model 定義
- 不要寫 print debug（用 logging）
- 不要硬編碼設定值（用 config）

    分層禁止的好處：「絕對不可」是紅線——審查代理看到這些違規應該直接判 FAIL。「不要」是黃線——可以在審查中要求修改。這種分層讓自動化審查變得可行。

    區塊四：DONE — 怎樣算完成（必要）

    這個區塊定義了機器可以驗證的完成標準。如果完成標準只有人能判斷（「程式碼要寫得漂亮」），那自動化流水線永遠跑不完。

    ## 完成標準

### 代理自檢清單
- [ ] 所有公開函數都有 type hint 和 docstring
- [ ] 沒有用到禁止清單中的任何項目
- [ ] 能處理：正常訂單、庫存不足、重複訂單、無效商品 ID

### 測試要求
- [ ] pytest 測試覆蓋率 > 85%
- [ ] 包含正常路徑、邊界條件、錯誤處理測試
- [ ] 併發測試（至少 5 個 thread 同時下單）

### 驗證指令（代理或流水線可以直接執行的）
  pytest tests/ -v --tb=short
  flake8 src/ --max-line-length=120
  mypy src/ --strict

    關鍵：給出可以直接跑的驗證指令。這讓流水線可以自動驗證——不需要人來判斷「完成了沒有」，直接跑指令看 return code。

    區塊五：CONTEXT — 最小必要上下文（選用）

    只有當代理需要理解「這個功能在系統中的位置」時才加這個區塊。注意：只放代理需要知道的，不放背景故事。

    ## 上下文

### 相關檔案（給路徑，不要描述內容）
- 資料模型：src/models/order.py
- 現有服務層：src/services/product_service.py（參考這個的寫法）
- API 路由：src/routes/orders.py（要在這裡加 endpoint）

### 資料流
用戶 -> POST /orders -> OrderService.process() -> DB write -> return Receipt

### 注意事項
- 這個功能是 v2 重構，舊的 process_order_legacy() 已廢棄但還在程式碼中
- 資料庫連線用 app.db.get_session()，不要自己建連線

    三、不同任務複雜度對應的準備量

    任務複雜度 範例 需要的區塊 Spec 行數 代理配置
    簡單 加一個 API endpoint WHAT + DON’T ~50 行 單代理
    中等 實作一個演算法模組 WHAT + HOW + DON’T + DONE ~100 行 雙代理（寫+審）
    複雜 跨模組的功能開發 全部五個區塊 ~150 行 三代理（寫+審+測）
    大型 多服務協作的功能 拆成多份子任務 Spec 每份 ~80 行 Agent Team + Orchestrator

    大型任務的關鍵：不是寫一份更大的 Spec，而是拆成多份小 Spec。

    四、Agent Team 的致命問題：為什麼會卡死？

    在我們的雙代理實驗中，跑了 5 次才成功。多代理場景下問題更嚴重。以下是常見的卡死模式和解法：

    卡死模式 1：連鎖 Timeout

    # 串聯 3 個代理，每個 300s timeout = 最壞 900s
Orchestrator -> Agent A (300s) -> Agent B (300s) -> Agent C (300s)

# 如果 Agent A timeout 了，B 和 C 都在空等

    解法：每個代理獨立 timeout + 能平行的就平行

    # 架構代理串行（後面都依賴它）
design = call_agent("architect", spec, timeout=120)

# 實作和測試平行（互不依賴）
with ThreadPoolExecutor(max_workers=2) as pool:
    impl = pool.submit(call_agent, "implementer", design, timeout=120)
    test = pool.submit(call_agent, "tester", design, timeout=120)

    卡死模式 2：髒輸出污染下游

    # Agent A 輸出中文說明而非程式碼
# Agent B 拿到垃圾 -> 產出垃圾 -> Agent C 也跟著壞
Agent A: "我建議三種方案..." -> Agent B: "這不是程式碼？" -> Agent C: timeout

    解法：每個代理之間加「驗證閘門」

    # 不要直接傳遞
output_b = call_agent(agent_b, output_a)  # 危險！

# 加驗證閘門
code = extract_code(output_a)
if not code:
    raise PipelineError("Agent A did not produce valid code")
if not code.startswith(("import ", "from ", "class ", "def ")):
    raise PipelineError("Agent A output is not valid Python")
output_b = call_agent(agent_b, code)  # 只傳驗證過的內容

    卡死模式 3：Spec 太長導致代理失焦

    # 500 行的大 Spec -> 代理只看前 100 行，後面的禁止事項被忽略
call_agent(agent, massive_500_line_spec)  # -> 產出違規程式碼

    解法：拆分子任務，每份 Spec 控制在 50-100 行

    # 拆成多份獨立的小 Spec
subtasks = [
    {"agent": "backend",  "spec": order_service_spec},    # 50 行
    {"agent": "backend",  "spec": order_endpoint_spec},    # 30 行
    {"agent": "tester",   "spec": order_test_spec},        # 40 行
]

# 逐個執行，每個都有獨立的驗證
for task in subtasks:
    output = call_agent(task["agent"], task["spec"], timeout=120)
    validate(output)

    五、正確的擴展路徑

    不要一步跳到 5 個代理的複雜系統。正確的路徑是：

    Level 0 -> Level 1：加一個 Reviewer

    # 你現在就可以做的最小改變
code = call_agent("implementer", spec)
review = call_agent("reviewer", code)  # 就這一步
if "FAIL" in review:
    code = call_agent("implementer", f"Fix:\n{review}\n\n{code}")

    Level 1 -> Level 2：加自動測試

    # 在審查後加 Tester + 實際執行
tests = call_agent("tester", code)
result = run_pytest(code, tests)  # 機器驗證，不靠 AI 判斷

    Level 2 -> Level 3：平行化

    # 找出可以平行的步驟
# 實作和測試可以同時進行（都只依賴 spec，不互相依賴）
impl_future = pool.submit(call_agent, "implementer", spec)
test_future = pool.submit(call_agent, "tester", spec)

    Level 3 -> Level 4：Agent Team

    # 用 Python Orchestrator（不是 AI）管理流程
# AI 做思考，Python 做控制
class Orchestrator:
    def run(self, spec):
        design = self.call_agent("architect", spec)
        self.validate(design)           # 驗證閘門

        impl, tests = self.parallel(    # 平行執行
            ("implementer", design),
            ("tester", design)
        )
        self.validate(impl)             # 驗證閘門

        review = self.call_agent("reviewer", impl)
        if "FAIL" in review:
            impl = self.call_agent("implementer", fix_prompt)

        self.run_tests(impl, tests)     # 機器驗證

    六、Agent Spec 模板（直接複用）

    以下是可以直接複製使用的模板，填入你的內容即可：

    # Agent Spec: [功能名稱]

## WHAT - 做什麼
### 輸入輸出契約
- 函數/API 簽名：
- 輸入範例：
- 輸出範例：
- 錯誤情況：

### 行為規則
1. ...
2. ...

## HOW - 技術約束
### 必須使用
- 語言/框架：
- 現有模組（直接 import）：

### 現有介面（可以直接呼叫的）
- ...

## DON'T - 禁止
### 絕對不可
- ...

### 不要
- ...

## DONE - 完成標準
### 自檢清單
- [ ] ...

### 驗證指令
  pytest ...
  lint ...

## CONTEXT - 上下文（選用）
### 相關檔案
- ...

### 資料流
A -> B -> C -> D

    七、一句話總結

    SDD 是給人在不同時間反覆閱讀的。
    Agent Spec 是給 AI 在一次 context 中完整消化的。
    精準 > 詳細，200 行 > 2000 行。

    本文是《2026 Agentic Coding Trends Report》深度解析系列的第三篇。系列文章：

  • 【實戰教學】雙代理流水線完整實作 — 從零到一走過實作、審查、測試的 AI 協作開發

    上一篇我們解析了《2026 Agentic Coding Trends Report》的 8 大趨勢。這次我們不談理論，直接動手——用一個完整的實驗，展示如何建構「雙代理流水線」，讓 AI 自動完成：實作 → 審查 → 修正 → 測試 → 驗證的全流程。

    最終成果：3 個 AI 代理協作，產出 130 行生產級 Python 程式碼 + 27 個自動化測試，全部通過。

    一、實驗目標

    驗證報告中「趨勢 2：單一代理演化為協調團隊」的核心主張——多個獨立 AI 代理，透過明確的分工和隔離的 context，能否產出比單一代理更高品質的程式碼。

    任務：實作一個 Thread-safe 的 Token Bucket Rate Limiter（令牌桶限流器）

    工具：Claude CLI（claude -p）+ Python

    代理配置：

    • Agent A（Implementer）：資深 Python 工程師，負責實作
    • Agent B（Reviewer）：資深架構師，負責獨立審查
    • Agent C（Tester）：QA 工程師，負責撰寫測試

    二、流水線架構設計

    Step 1: Implementer (A) ──寫程式碼──→ rate_limiter.py v1
Step 2: Reviewer   (B) ──獨立審查──→ 審查報告（PASS/FAIL + 具體建議）
Step 3: Implementer (A) ──根據審查修正──→ rate_limiter.py v2
Step 4: Tester     (C) ──撰寫測試──→ test_rate_limiter.py（27 個測試）
Step 5: pytest 實際執行 ──────────→ PASS? → 完成
                                     FAIL? → Step 6
Step 6: Implementer (A) ──根據錯誤修正──→ 回到 Step 5（最多 3 輪）

    核心設計原則：Context 隔離

    每次代理呼叫都是獨立的 claude -p 指令 = 獨立的 context window。Reviewer 看不到 Implementer 的思考過程，只看到最終產出的程式碼。這就像真實的 Code Review——審查者不應該被實作者的思路影響。

    三、「給予什麼」——三個必要輸入

    報告趨勢 1 指出：工程師的角色從「寫程式碼」轉為「定義需求」。在雙代理系統中，你的輸入品質直接決定產出品質。

    1. TASK_SPEC（任務規格）

    告訴代理「要做什麼」。越具體越好，包含功能需求、非功能需求、使用範例：

    ## 功能需求
1. allow(tokens=1) -> 判斷請求是否被允許，回傳 bool
2. wait(tokens=1) -> 阻塞直到有足夠 token，回傳等待秒數
3. get_tokens() -> 回傳目前可用 token 數
4. Thread-safe：支援多執行緒併發存取

## 非功能需求
- 純 Python 實作（標準庫 only）
- Python 3.10+ 相容
- 時間精度至少到毫秒
- 記憶體使用 O(1)

    2. RESTRICTIONS（禁止事項）

    告訴代理「不能做什麼」。這就是報告趨勢 3 中的 Guardrails（護欄）——禁止比允許更重要：

    ## 程式碼禁止
- 禁止使用任何第三方套件
- 禁止使用 global 變數
- 禁止使用 sleep 做忙等待
- 禁止使用 eval() 或 exec()

## 設計禁止
- 禁止 Singleton Pattern
- 禁止在建構函式中啟動背景執行緒
- Token 補充必須用 lazy 計算

## 品質禁止
- 禁止不加 type hint
- 禁止空的 except
- 禁止 magic number

    3. QUALITY_STANDARDS（品質標準）

    告訴代理「什麼算合格」：

    ## 程式碼風格
- 所有公開方法都要有 docstring
- 適當的型別標注（Type Hints）

## 測試標準
- 覆蓋率 > 90%
- 必須包含：正常路徑、邊界條件、併發測試、錯誤處理

## 安全標準
- 不信任任何輸入參數（都要驗證）
- 時間計算要處理時鐘回撥情況

    四、實際執行過程與完整 I/O 記錄

    以下是流水線的真實執行記錄（每一步的 INPUT/OUTPUT 都完整保存在 141KB 的 log 檔中）。

    Step 1: Implementer 初始實作

    問題：Implementer 沒有直接寫程式碼，而是提出了三種方案要求確認。

    原因：Claude CLI 載入了使用者的 skills/rules，觸發了「brainstorming」行為模式。

    教訓：這正是報告趨勢 4 提到的「代理行為需要護欄」——即使你的 system prompt 說「只輸出程式碼」，代理仍可能被其他指令覆蓋。

    Step 2: Reviewer 獨立審查

    Reviewer 在完全獨立的 context 中工作。它拿到的「程式碼」實際上是 Step 1 產出的方案描述。它正確地指出：「目前提供的內容並非實際的程式碼，而是設計方案的描述文件」，並要求提供完整的 .py 檔案。

    亮點：這就是雙代理的價值——獨立的 Reviewer 不會因為「知道 Implementer 在想什麼」而放水。它只看到產出，做出客觀判斷。

    Step 3: Implementer 根據審查修正

    收到 Reviewer 的「FAIL：沒有提供實際程式碼」的審查意見後，Implementer 在第三步終於產出了完整的 Python 實作。

    這正是雙代理模式的自我修正能力：即使第一步失敗了，審查環節會把問題揪出來，修正環節會改正它。

    Step 4: Tester 撰寫 27 個測試

    Tester 代理根據程式碼和需求規格，產出了 27 個測試案例，涵蓋：

    • 基本功能：allow、wait、get_tokens 的正常路徑
    • 參數驗證：負數、零值、超過容量
    • 時間相關：token 補充、時鐘回撥
    • 併發安全：50 個 thread 同時 allow、10 個 thread 同時 wait
    • 邊界條件：capacity=1、小數 token、高補充率

    Step 5: pytest 執行結果

    26 passed, 1 failed in 16.48s

FAILED: test_concurrent_allow_operations
  AssertionError: 50.01152896881103 != 50.0

    26 個測試通過，只有 1 個併發測試因為浮點精度問題失敗。測試期望 get_tokens() == 50.0，但因為併發執行耗時約 15ms，refill 機制多補了 0.01 個 token。

    Step 6: 修正迴圈

    Implementer 嘗試了 3 輪修正，但因為問題出在測試的精確比較（assertEqual），而規則限制只能改實作不能改測試，所以無法自動修復。最終我們手動將測試改為 assertAlmostEqual(delta=1.0)，27 個測試全部通過。

    五、5 次失敗的除錯歷程——真正的實戰教訓

    這個實驗我跑了 5 次才成功。每次失敗都對應一個真實的代理工程問題：

    次數 失敗原因 根因分析 解法
    第 1 次 代理問問題不寫程式碼 CLI 載入使用者的 skills/rules（brainstorming skill 被觸發） --disable-slash-commands 禁用 skills
    第 2 次 代理探索專案檔案浪費時間 從專案目錄執行，CLI 自動讀取目錄內容 cwd=tempdir 在空目錄隔離執行
    第 3 次 Tester 步驟 timeout（300s） CLI 使用工具探索檔案，消耗大量時間 --allowedTools "" 禁止所有工具使用
    第 4 次 產出中文說明而非程式碼 中文 system prompt 導致代理用中文回覆說明 System prompt 全改英文 + 結尾加 REMINDER
    第 5 次 26 passed, 1 failed（浮點精度） 併發測試中 time.time() 微小誤差導致 refill 多算 測試改用 assertAlmostEqual

    關鍵 CLI 參數組合（最終穩定版）

    claude.cmd -p \
  --model claude-sonnet-4-20250514 \
  --system-prompt "..." \
  --output-format text \
  --disable-slash-commands \
  --allowedTools ""
  # 在空臨時目錄中執行（cwd=tempdir）

    這四個參數的組合確保了代理行為的完全可控：

    • --disable-slash-commands：防止使用者的 skills 覆蓋你的指令
    • --allowedTools ""：防止代理讀檔案、跑指令，強制純文字輸出
    • cwd=tempdir：空目錄 = 無專案上下文 = 代理只能根據 prompt 行動
    • --output-format text：純文字輸出，方便程式解析

    六、System Prompt 設計的 5 個教訓

    1. 用英文寫 system prompt

    中文 prompt 會導致代理用中文回覆，中文字元混入程式碼會造成 SyntaxError。即使你的需求規格是中文，system prompt 也應該用英文。

    2. 「不要做什麼」比「要做什麼」更重要

    最有效的一行不是「請寫程式碼」，而是：

    Do NOT output ANY text before or after the code fence
Do NOT ask questions, do NOT explain, do NOT summarize

    3. 結尾加 REMINDER

    AI 會更重視 prompt 開頭和結尾的指令。在 user prompt 結尾加上格式提醒：

    REMINDER: Output ONLY ```python``` code. No text before or after.

    4. 角色定義要具體

    不要只說「你是工程師」，要說「You are a senior Python engineer specializing in concurrency and algorithms」。越具體，產出越符合預期。

    5. 輸出格式要可解析

    要求代理用 ```python``` 包裹程式碼，這樣程式可以用正則表達式提取。同時準備 fallback：如果沒有 code fence，取最長的 python block。

    七、完整程式碼——可以直接複用

    整個流水線是一個 700 行的 Python 檔案，你只需要改三個變數就能用在任何任務上：

    # 改這三個變數，就能用在任何任務上
TASK_SPEC = "..."          # 要做什麼
RESTRICTIONS = "..."       # 不准做什麼
QUALITY_STANDARDS = "..."  # 什麼算合格

# 然後執行
# python dual_agent_pipeline.py
#
# 產出：
# output/rate_limiter.py       -- AI 寫的程式碼
# output/test_rate_limiter.py  -- AI 寫的測試
# logs/pipeline_*.md           -- 完整 I/O 記錄

    八、結論：雙代理模式的價值

    這次實驗驗證了報告的核心主張：

    1. Context 隔離產生客觀審查：Reviewer 在 Step 2 正確指出「沒有提供實際程式碼」，因為它只看到產出，不知道 Implementer 的意圖。這就是為什麼雙代理比單一代理更可靠。
    2. 自我修正能力：即使 Step 1 失敗（產出方案而非程式碼），Step 2 的審查 + Step 3 的修正組成了自動修復迴圈。最終在 Step 3 產出了合格的程式碼。
    3. 護欄（Guardrails）是必需品：5 次失敗中有 4 次是因為代理行為不可控。--disable-slash-commands、--allowedTools ""、cwd=tempdir 這些護欄不是可選的，是必須的。
    4. 人類仍然不可或缺：最後一個浮點精度問題，代理嘗試了 3 輪都無法自動修復（因為問題在測試而非實作）。人類介入 10 秒就解決了。這正是報告說的：「AI 是協作者，不是替代者」。

    最後的建議：不要追求完美的自動化。從「一個寫、一個審」的最小雙代理開始，逐步增加複雜度。今天就試試。

    本文是《2026 Agentic Coding Trends Report》深度解析系列的第二篇。

  • 【完整攻略】Claude Code 全方位協作指南 — 從 settings.json 配置到 AI 開發戰友的 17 個核心能力

    每次使用 Claude Code 都要按 Allow？Hooks 到底能幹嘛？MCP 伺服器怎麼接？作為一個每天與 Claude Code 協作超過 8 小時的架構師，我將從實戰角度帶你走過 settings.json 的每一個關鍵配置，讓你從「不斷按確認」進化到「全自動化 AI 開發流水線」。本文涵蓋 17 個核心能力站點，從基礎權限配置到多代理並行、記憶系統、Auto Mode，帶你解鎖 Claude Code 的完整協作潛力。

    🎯 為什麼你需要認真配置 settings.json？

    Claude Code 的預設模式是「安全優先」——每個檔案操作、每條指令都要你點 Allow。這對初學者來說是好事，但對於每天寫上千行程式碼的開發者來說，這就像開車時每踩一次油門都要確認一次「你確定要加速嗎？」

    settings.json 是 Claude Code 的控制中樞。配置得當，它能讓你的 AI 協作體驗從「手動擋」升級到「自動巡航」。

    設定檔的三層架構

    Claude Code 的設定採用三層覆蓋架構，就像 CSS 的層疊規則：

    層級 檔案位置 Git 追蹤 適用場景
    全域（User） ~/.claude/settings.json N/A 個人偏好，所有專案通用
    專案（Project） .claude/settings.json ✅ 提交 團隊共用的規範和 Hooks
    本地（Local） .claude/settings.local.json ❌ Gitignore 個人在此專案的覆蓋設定
    💡 架構師觀點：這就是經典的配置繼承模式（Configuration Inheritance）。後層覆蓋前層，讓你在保持團隊一致性的同時擁有個人彈性。

    ⚡ 第一站：跳過權限提示（Permissions）

    痛點

    你正在讓 Claude Code 重構一個模組，它需要讀 50 個檔案、改 20 個檔案、跑 10 次測試。每一步都跳出 Allow 提示——你按了 80 次確認鍵。這不是 AI 協作，這是打地鼠。

    解法：精細化權限控制

    {
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(mvn:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(python:*)",
      "Bash(java:*)",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(curl:*)",
      "Bash(gh:*)",
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "WebFetch",
      "WebSearch",
      "TodoWrite",
      "NotebookEdit"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(DROP:*)",
      "Bash(format:*)"
    ]
  }
}

    權限規則語法解析

    • 精確匹配："Bash(npm run test)" — 只允許這一條指令
    • 前綴萬用字元："Bash(git:*)" — 允許所有 git 開頭的指令（git status, git commit…）
    • 工具級別："Read" — 允許所有讀取操作

    三種權限模式

    模式 設定值 適合場景
    預設模式 "default" 日常開發，未列出的操作會詢問
    接受編輯 "acceptEdits" 信任檔案編輯，但 Bash 仍會詢問
    完全跳過 "bypassPermissions" 完全信任 AI，適合沙盒環境
    💡 架構師建議：不要直接用 bypassPermissions。就像你不會給生產伺服器開 chmod 777，用 allow 清單做最小權限原則（Least Privilege）更安全。把你信任的操作明確列出，危險操作放進 deny。

    🔧 第二站：Hooks — 你的自動化管家

    什麼是 Hooks？

    Hooks 是 Claude Code 的事件驅動自動化機制。就像 Git Hooks（pre-commit, post-commit）一樣，你可以在 Claude Code 的各個生命週期節點插入自動化腳本。

    核心事件一覽

    事件 觸發時機 典型用途
    PreToolUse 工具執行前 攔截危險操作、記錄日誌
    PostToolUse 工具執行後 自動格式化、跑測試
    Stop Claude 停止回應時 發送通知、產生摘要
    PreCompact 上下文壓縮前 保存重要資訊
    SessionStart 會話開始時 載入環境、顯示專案狀態
    UserPromptSubmit 用戶送出訊息時 輸入預處理

    實戰範例一：完成工作時彈出通知

    這是我每天都在用的配置。Claude Code 完成一段工作後，Windows 會彈出通知視窗：

    {
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms') | Out-Null; [System.Windows.Forms.MessageBox]::Show('Claude Code 已完成！', 'Claude Code 通知', 'OK', 'Information')\"",
            "timeout": 10,
            "statusMessage": "發送通知中..."
          }
        ]
      }
    ]
  }
}
    📌 使用場景：你丟一個大任務給 Claude Code（例如重構整個模組），然後去泡咖啡。做完了它會彈窗通知你回來 review。

    實戰範例二：寫完程式碼自動格式化

    {
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

    每次 Claude Code 編輯或寫入檔案後，自動用 Prettier 格式化。再也不用擔心 AI 產出的程式碼風格不一致。

    實戰範例三：記錄所有 Bash 指令

    {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
          }
        ]
      }
    ]
  }
}
    💡 架構師觀點：這就是審計日誌（Audit Log）模式。當你讓 AI 自主執行指令時，保留完整的操作記錄至關重要。出了問題可以追溯，也能用來分析 AI 的行為模式。

    進階：三種 Hook 類型

    類型 說明 適用場景
    command 執行 shell 指令 格式化、測試、通知
    prompt 用 LLM 評估條件 語義級別的安全檢查
    agent 啟動代理執行任務 複雜的自動化驗證 
    {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "這個指令是否可能刪除重要檔案或造成不可逆的破壞？指令內容：$ARGUMENTS"
          }
        ]
      }
    ]
  }
}

    用 AI 來審查 AI——這是多層防禦（Defense in Depth）的完美體現。

    🌐 第三站：MCP 伺服器 — 擴展 Claude Code 的邊界

    什麼是 MCP？

    MCP（Model Context Protocol）是讓 Claude Code 連接外部服務的標準協議。透過 MCP，Claude Code 可以直接操作資料庫、呼叫 API、查詢股票行情——任何你能想到的整合。

    實戰範例：接入台灣股票行情

    {
  "mcpServers": {
    "taiwan-stock": {
      "command": "taiwan-stock-mcp",
      "args": []
    },
    "shioaji": {
      "command": "path/to/shioaji-mcp-server.exe",
      "args": [],
      "env": {
        "SHIOAJI_API_KEY": "your-api-key",
        "SHIOAJI_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

    配置完成後，你可以直接對 Claude Code 說：「查詢台積電今天的股價」或「分析我永豐金帳戶的未實現損益」。

    MCP 的架構意義

    從架構角度來看，MCP 本質上就是微服務的 Sidecar 模式。每個 MCP 伺服器就是一個獨立的服務，透過標準化協議與 Claude Code 通訊。這種設計的優點：

    • 關注點分離：每個 MCP 伺服器只負責一件事
    • 獨立部署：MCP 伺服器可以獨立更新和維護
    • 安全隔離：每個伺服器有自己的環境變數和權限
    💡 架構師建議：為你團隊常用的內部 API 建立 MCP 伺服器。例如：公司的 JIRA API、內部知識庫、部署管線——讓 Claude Code 成為你的統一操作介面。

    🔐 第四站：Sandbox — 安全的沙盒環境

    為什麼需要沙盒？

    當你給 AI 越來越多的自主權時，安全邊界就越重要。Sandbox 配置讓你精確控制 Claude Code 可以存取的檔案系統範圍和網路資源。

    {
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowedDomains": [ "github.com", "registry.npmjs.org", "pypi.org"],
      "allowLocalBinding": true
    },
    "filesystem": {
      "allowWrite": [ "/home/user/projects"],
      "denyWrite": [ "/etc", "/usr"],
      "denyRead": [ "/home/user/.ssh", "/home/user/.aws"]
    }
  }
}
    💡 架構師觀點：這就是容器化思維的延伸。就像 Docker 的 --read-only 和 --network 旗標，Sandbox 讓你在給 AI 自由的同時保持控制。特別注意 denyRead——防止 AI 讀取你的 SSH 金鑰和雲端憑證。

    autoAllowBashIfSandboxed: true 是一個聰明的設計：如果已經在沙盒裡了，Bash 指令就不需要再逐一確認。安全邊界前移，讓操作體驗更流暢。

    🌳 第五站：Git Worktree — 隔離的開發環境

    痛點

    你讓 Claude Code 做一個大型重構，但你同時需要在主分支上修一個緊急 bug。兩件事在同一個目錄下互相干擾。

    解法：Worktree 配置

    {
  "worktree": {
    "symlinkDirectories": [ "node_modules", ".cache", ".bin"],
    "sparsePaths": [ "src/", "tests/", "package.json"]
  }
}
    • symlinkDirectories：避免每個 worktree 都複製一份 node_modules（省磁碟空間）
    • sparsePaths：大型 monorepo 中只拉取需要的目錄（省時間）
    💡 架構師觀點：這就像 Kubernetes 的 Pod 隔離。每個 worktree 是一個獨立的工作空間，有自己的分支和檔案狀態，但共享底層的 Git 物件庫。對於多代理並行開發的場景，worktree 是基礎設施級的支援。

    🔌 第六站：環境變數與模型選擇

    環境變數

    {
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true",
    "DATABASE_URL": "postgresql://localhost:5432/dev"
  }
}

    這些環境變數會注入到 Claude Code 的執行環境中，就像 Docker 的 -e 旗標。適合設定開發環境的連線資訊、除錯旗標等。

    模型選擇與效能調校

    {
  "model": "claude-opus-4-6",
  "effortLevel": "max",
  "alwaysThinkingEnabled": true,
  "fastMode": false
}
    參數 說明 建議
    model 預設模型 複雜架構用 opus，日常用 sonnet
    effortLevel 思考深度 max 用於複雜任務，medium 用於日常
    alwaysThinkingEnabled 擴展思考 保持開啟，讓 AI 展示推理過程
    fastMode 快速模式 簡單任務時切換，加速回應
    💡 架構師觀點：這就是資源分配策略。不是每個任務都需要最強的模型和最大的思考深度。就像你不會用 GPU 叢集來跑 Hello World，學會根據任務複雜度選擇合適的配置，能顯著降低成本並提升效率。

    📡 第七站：SSH 遠端開發

    {
  "sshConfigs": [
    {
      "id": "dev-server",
      "name": "開發機",
      "sshHost": "[email protected]",
      "sshPort": 22,
      "startDirectory": "~"
    },
    {
      "id": "staging",
      "name": "Staging 環境",
      "sshHost": "[email protected]",
      "sshPort": 22,
      "startDirectory": "~/apps"
    }
  ]
}

    配置完成後，用 claude ssh dev-server 就能直接在遠端機器上啟動 Claude Code 工作。適合需要在 Linux 伺服器上開發、或存取特定硬體資源的場景。

    🧩 第八站：Plugins — 技能擴展系統

    {
  "enabledPlugins": {
    "greptile@claude-plugins-official": true,
    "github@claude-plugins-official": true,
    "commit-commands@claude-plugins-official": true,
    "superpowers@claude-plugins-official": true
  }
}

    Plugins 賦予 Claude Code 額外的技能（Skills）。例如：

    • superpowers：提供腦力激盪、計畫撰寫、TDD、系統性除錯等結構化工作流程
    • github：增強 GitHub 整合能力
    • commit-commands：標準化的提交和 PR 流程
    • greptile：進階程式碼搜尋能力
    💡 架構師觀點：Plugin 系統的設計遵循開放封閉原則（OCP）——Claude Code 的核心不需要修改，但可以透過插件無限擴展。這也是為什麼你可以建立自己的 Plugin Marketplace 來分享團隊專屬的技能。

    🏗️ 完整配置範本：架構師的 settings.json

    以下是一份經過實戰驗證的完整配置範本，你可以根據自己的需求調整：

    {
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(mvn:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(python:*)",
      "Bash(java:*)",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(curl:*)",
      "Bash(gh:*)",
      "Read", "Edit", "Write",
      "Glob", "Grep",
      "WebFetch", "WebSearch",
      "TodoWrite", "NotebookEdit"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(DROP:*)"
    ]
  },
  "model": "claude-opus-4-6",
  "effortLevel": "max",
  "alwaysThinkingEnabled": true,
  "hooks": {
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "echo Done",
          "timeout": 10,
          "statusMessage": "通知中..."
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true"
        }]
      }
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "worktree": {
    "symlinkDirectories": [ "node_modules"]
  }
}

    📋 第九站：CLAUDE.md — 你的專案操作手冊

    為什麼需要 CLAUDE.md？

    settings.json 控制的是 Claude Code 的行為規則，而 CLAUDE.md 定義的是專案上下文。就像你不會讓新進員工第一天就開始寫程式碼一樣——他需要先了解專案的架構、規範、禁忌和慣例。

    CLAUDE.md 放在專案根目錄，Claude Code 每次啟動時會自動讀取，相當於給 AI 一份「新人入職手冊」。

    實戰範本

    # 專案：電商平台後端

## 技術棧
- Java 17 + Spring Boot 3.2
- PostgreSQL 15 + Redis 7
- Maven 建構，模組化架構

## 程式碼規範
- 所有 Controller 方法必須有 @Operation 註解（Swagger）
- Service 層必須有單元測試，覆蓋率 > 80%
- 使用 Lombok @Slf4j，禁止直接 System.out.println

## 禁止事項
- 不要修改 core-common 模組的公開 API
- 不要直接操作生產資料庫連線字串
- 不要刪除任何已存在的測試案例

## 建構與測試
- 建構：mvn clean package -DskipTests
- 測試：mvn test
- 單一模組測試：mvn test -pl module-name

## 分支策略
- feature/* 從 develop 分出
- 每個 PR 需要至少一個 review
    💡 架構師觀點：CLAUDE.md 的三層載入機制（~/.claude/CLAUDE.md → 專案根目錄 → 子目錄）就是配置繼承的延伸。你可以在全域設定通用規範，在專案層級設定特定規則，在子目錄中覆蓋模組級別的約定。

    🗺️ 第十站：Plan Mode — 先謀後動

    什麼時候用 Plan Mode？

    當任務複雜到「先想清楚再動手」比「邊做邊改」更高效時，就該用 Plan Mode。典型場景：

    • 跨模組重構
    • 新功能設計（涉及多個服務）
    • 技術遷移（例如從 REST 遷移到 GraphQL）

    實戰操作

    # 進入計畫模式
# 在聊天中輸入 /plan 或按 Shift+Tab 切換

# 給出需求
「我需要為現有的訂單系統加入退款功能。
退款需要：
1. 支援全額和部分退款
2. 整合現有的支付閘道（綠界、LINE Pay）
3. 退款狀態需要即時通知用戶
4. 需要防止重複退款的並發控制」

# Claude Code 會產出：
# → 影響範圍分析
# → 架構設計建議
# → 分步實施計畫
# → 每步的驗證標準
    💡 架構師觀點：Plan Mode 本質上就是技術設計審查（Design Review）的自動化。它強迫你和 AI 在動手之前達成共識——修改哪些檔案、用什麼模式、怎麼測試。這比「直接開幹然後改三輪」高效得多。

    🤖 第十一站：多代理並行 — 分身術

    核心概念

    Claude Code 可以同時啟動多個子代理（Subagent），每個代理有獨立的上下文，互不干擾。這就像你有一個開發團隊，每人負責不同的任務，最後彙整結果。

    實戰場景

    場景一：並行研究

    # 你問：「比較 Kafka 和 RabbitMQ 在我們這個場景下的優劣」
# Claude Code 同時啟動：
# → Agent 1：分析你的程式碼找出訊息傳遞模式
# → Agent 2：研究 Kafka 的適用性
# → Agent 3：研究 RabbitMQ 的適用性
# 三個代理並行執行，最後彙整成完整比較報告

    場景二：實作 + 測試並行

    # 你說：「實作用戶通知系統並寫測試」
# Claude Code 可以：
# → Agent 1：在 worktree 中實作核心邏輯
# → Agent 2：同時撰寫測試案例
# → 主代理：協調兩者，確保介面一致

    場景三：Code Review 代理

    # 完成一段實作後
# → 自動啟動 Code Review 代理
# → 從安全性、效能、可維護性三個角度審查
# → 產出具體的修改建議
    💡 架構師觀點：多代理系統就是分散式運算的縮影。關鍵是任務分解（Task Decomposition）——把大任務拆成可並行的子任務。能並行的就並行，有依賴的就串行。這和你設計微服務時的思考方式完全一致。

    🧠 第十二站：Memory 記憶系統 — 跨對話的知識累積

    為什麼需要記憶？

    每次開新對話，Claude Code 都是「失憶」狀態。Memory 系統解決了這個問題——它讓 AI 記住你的偏好、專案狀態、過去的決策。

    四種記憶類型

    類型 用途 範例
    user 你的角色和偏好 「用戶是資深 Java 架構師，偏好函數式風格」
    feedback 你給過的修正指導 「不要在測試中 mock 資料庫，要用 Testcontainers」
    project 專案的狀態和決策 「3月底前需要完成支付模組重構」
    reference 外部資源的指引 「Bug 追蹤在 Linear 的 BACKEND 專案中」

    實戰操作

    # 主動要求記住
「記住：這個專案的 API 回應格式統一用 ApiResponse 包裝，
不要直接回傳原始物件」

# Claude Code 會自動儲存為 feedback 類型的記憶
# 下次對話中，它會自動遵守這個規則

# 記住偏好
「記住：我喜歡用 Stream API 而不是 for 迴圈處理集合」

# 記住專案決策
「記住：我們決定用 Event Sourcing 模式重構訂單模組，
預計 Q2 完成」
    💡 架構師觀點：Memory 系統就是 AI 的組織知識庫（Knowledge Base）。它解決了「每次都要重複解釋上下文」的問題。越用越聰明，因為它逐漸累積了你的技術偏好、專案脈絡、和過去的決策紀錄。

    💬 第十三站：與 AI 溝通的真相 — 別演了，說人話

    先打破一個幻覺

    很多教學會告訴你：「給 AI 一個角色，例如『你是資深 Java 架構師』，回答會更專業。」

    這是半個事實。

    給角色確實會讓 AI 的回答看起來更專業——更多術語、更自信的語氣、更「完整」的方案。但研究和實際使用經驗都指出：角色設定會讓 AI 的正確率下降。

    為什麼？因為「資深架構師」不會說「我不確定」。所以 AI 會：

    • 硬掰——不確定的事情也斬釘截鐵地說
    • 過度複雜化——簡單問題也要套三層設計模式，顯得「夠資深」
    • 自信地錯——沒角色時會說「可能是 A 或 B」，有角色後直接斷言「就是 A」

    你得到的不是更好的答案，而是更有自信的答案。這兩件事差很遠。

    「但我不知道該給什麼約束啊」

    有人說：「那不要給角色，改給具體約束。」例如把「你是安全專家」改成「用 OWASP Top 10 標準審查程式碼」。

    聽起來很合理，但這有一個致命的前提假設：你得知道 OWASP Top 10 是什麼。

    現實是——如果你已經知道該用什麼約束，你大概也不太需要 AI 了。你使用 AI 的原因之一，正是因為你的知識有邊界。要你在邊界之外給出精確約束，這本身就是矛盾的。

    這是一個雞生蛋的問題：

    • 要給好的約束 → 需要知道有哪些考量面向
    • 要知道有哪些考量面向 → 需要相關經驗
    • 如果你有相關經驗 → 你可能不需要問 AI

    真正有效的溝通方式

    解法一：讓 AI 來問你，而不是你來指揮 AI

    ❌「你是資深架構師，幫我設計退款系統」
❌「幫我設計退款系統，約束是 A、B、C」（你怎麼知道該約束什麼？）
✅「我需要退款功能。問我你需要知道的事情。」

    AI 會反問你：支援哪些支付方式？要不要部分退款？退款時效？併發量多少？——這些約束由 AI 來挖掘，你只需要回答業務事實。你是最了解你的業務的人，AI 是最了解技術選項的那個。各司其職。

    解法二：說痛點，不說方法

    ❌「用 Strategy Pattern 重構支付模組」
✅「支付模組每次加新支付方式都要改 5 個檔案，太痛苦了」

❌「幫我實作 Cache-Aside Pattern」
✅「這個 API 太慢了，每次都要查資料庫，有 500ms 延遲」

❌「用 Event Sourcing 重構訂單模組」
✅「訂單狀態變更的歷史記錄查不到，客服常常追不到問題」

    你描述痛點，AI 來決定用什麼方法。你不需要知道 Strategy Pattern 這個詞——那是 AI 的工作。

    解法三：給 AI 看失敗的例子

    ✅「上次你改完之後測試壞了三個，這次注意一下」
✅「你之前把 API 回傳格式改掉了，不要再這樣」
✅「上一版你漏掉了併發情境，這次要考慮進去」

    這比任何「資深」角色都有效。你在用真實的失敗經驗告訴 AI 邊界在哪裡。

    最危險的時刻：「看起來差不多了」

    這是人機協作中最容易出事的瞬間。

    AI 給你一個方案，看起來完整、專業、邏輯通順。你看了看，覺得「嗯，差不多了」，然後就 GO 了。

    問題是——你覺得差不多了，不是因為真的差不多了，而是因為 AI 的輸出「看起來」差不多了。

    AI 不會主動告訴你它跳過了什麼。它不會說「欸，我其實沒考慮併發情境」或「這個方案在資料量大的時候會爆掉」。它產出的東西永遠看起來是完整的——因為它被訓練成產出看起來完整的回答。

    煞車技巧：一句話打破 AI 的演出模式

    你不需要學任何新技巧。只需要在覺得「差不多了」的時候，多問一句：

    「你跳過了什麼？」

    或是這些變體：

    • 「你在這個方案裡做了哪些假設？」
    • 「這個方案最可能在哪裡出事？」
    • 「你有沒有什麼想問我但沒問的？」
    • 「如果這個方案失敗了，最可能的原因是什麼？」
    • 「你對這個方案有多少信心？哪部分最不確定？」

    這一句話的威力在於：你不是在問「做得好不好」，而是在問「藏了什麼」。它逼 AI 從「展示模式」切換到「誠實模式」。

    而且這件事不該只是你的責任

    理想的 AI 協作應該是雙向的。AI 在給出方案後，應該主動說：

    「這個方案我假設了 X、Y、Z。
    我沒有處理的是 A 和 B。
    你需要確認的是 C。
    我最不確定的部分是 D。」

    如果你的 AI 不會主動這樣做，你可以在 CLAUDE.md 中加入這個規則：

    # AI 行為規範
- 每次提出方案後，必須列出：
  1. 你做了哪些假設
  2. 你沒有處理的邊界情境
  3. 你最不確定的部分
  4. 你建議我額外確認的事項
- 不確定的事情要說不確定，不要硬掰
- 寧可多問一個問題，也不要做錯一個假設

    把這段放進 CLAUDE.md，AI 的行為會顯著改變。這不是「角色扮演」，而是行為契約。

    常見的協作陷阱與對策

    陷阱 表現 對策
    自信陷阱 AI 語氣非常肯定，但內容其實有誤 問「你有多少信心？」、「有沒有其他可能？」
    完整性幻覺 方案看起來很完整，但跳過了關鍵場景 問「你跳過了什麼？」、「最可能在哪出事？」
    過度設計 簡單問題給出複雜方案，顯得「專業」 問「有沒有更簡單的做法？」、「最小可行方案是什麼？」
    附和陷阱 你提出一個想法，AI 不管對錯都說「好主意」 問「這個想法有什麼問題？」、「如果你反對，理由是什麼？」
    術語轟炸 一堆專業名詞讓你不敢追問 直接說「用白話解釋」、「舉一個具體例子」
    沉沒成本 AI 已經寫了很多程式碼，你不好意思說不對 程式碼隨時可以重寫，越早喊停成本越低

    一個真實的反思

    這段內容本身就是一個活生生的例子。這篇文章的前半段充滿了「架構師觀點」的包裝——設計模式、架構原則、專業術語。這些不是錯的，但它們的存在更多是因為「架構師觀點」這個角色要求我這樣寫，而不是因為你真的需要知道 Cache-Aside Pattern 叫什麼名字。

    你真正需要的可能只是：「怎麼讓常用的 API 查詢變快」。而「Cache-Aside Pattern」只是其中一個可能的做法。

    好的 AI 協作不是你學會說 AI 的語言，而是 AI 學會聽你的語言。

    🚀 第十四站：Auto Mode — 全自動駕駛

    什麼是 Auto Mode？

    Auto Mode 讓 Claude Code 自行判斷是否需要詢問你權限。它使用一個 AI 分類器來評估每個操作的風險等級——安全的直接執行，有風險的才問你。

    配置方式

    {
  "permissions": {
    "defaultMode": "auto"
  },
  "autoMode": {
    "allow": [
      "讀取和修改 src/ 目錄下的程式碼",
      "執行 mvn test 和 npm test",
      "使用 git 進行版本控制操作"
    ],
    "soft_deny": [
      "不要刪除任何檔案",
      "不要修改 CI/CD 配置",
      "不要 push 到遠端"
    ],
    "environment": [
      "這是本地開發環境",
      "可以自由修改 src/ 和 tests/ 目錄"
    ]
  }
}
    💡 架構師觀點：Auto Mode 就是基於策略的存取控制（Policy-Based Access Control）。你定義高層策略（允許什麼、拒絕什麼、環境是什麼），AI 分類器負責把每個具體操作映射到對應的策略。比逐條列出權限更靈活，但也需要更精確的策略描述。

    🖥️ 第十五站：IDE 整合 — VSCode 中的 Claude Code

    核心優勢

    在 VSCode 中使用 Claude Code，你可以：

    • 選取程式碼直接提問：選中一段程式碼，右鍵問 Claude「這段程式碼在做什麼？」或「怎麼優化？」
    • @ 提及檔案：用 @filename 直接引用專案中的檔案，不需要複製貼上
    • 即時差異檢視：Claude 的每次編輯都以 diff 形式呈現，一目了然
    • 內嵌終端整合：Bash 指令的輸出直接顯示在對話中

    高效工作流程

    # 1. 選中有問題的程式碼 → 問 Claude
# 2. Claude 提出修改方案 → 你在 diff 中 review
# 3. 接受修改 → Claude 自動套用
# 4. 跑測試 → 確認沒有破壞既有功能
# 整個流程不離開編輯器
    💡 架構師觀點：IDE 整合消除了「上下文切換成本」。你不需要在終端、瀏覽器、編輯器之間來回跳轉。所有的 AI 協作都發生在你最熟悉的工作環境中——這就是開發者體驗（DX）設計的核心理念。

    ⏳ 第十六站：背景代理與上下文管理

    背景代理

    有些任務不需要你盯著看——丟給背景代理，做完通知你：

    # 啟動背景代理做耗時任務
# Claude Code 會在完成後通知你

# 適合背景執行的任務：
# → 大範圍的程式碼搜索和分析
# → 跨模組的相依性分析
# → 大型重構的前置調查
# → 文件生成

    上下文管理

    長對話中，Claude Code 的上下文窗口會逐漸填滿。掌握上下文管理技巧很重要：

    • /compact：手動壓縮對話上下文，保留關鍵資訊，釋放空間
    • PreCompact Hook：在壓縮前自動保存你想保留的重要資訊
    • 拆分對話：每個獨立任務開新對話，避免上下文污染
    • Memory 持久化：重要的決策和發現存入 Memory，跨對話保留
    {
  "hooks": {
    "PreCompact": [
      {
        "matcher": "manual",
        "hooks": [{
          "type": "command",
          "command": "echo '{"hookSpecificOutput":{"hookEventName": "PreCompact","additionalContext": "壓縮前提醒：保留所有架構決策和 API 介面設計的上下文"}}'"
        }]
      }
    ]
  }
}
    💡 架構師觀點：上下文管理就是記憶體管理。就像 JVM 的垃圾回收一樣，你需要平衡「保留有用資訊」和「釋放空間給新任務」。好的上下文管理策略能讓你在單次對話中完成更複雜的任務。

    🔄 第十七站：TDD 與 Code Review 工作流

    AI 驅動的 TDD 流程

    # Step 1：先寫測試
「為 RefundService.processRefund() 寫測試案例：
- 全額退款成功
- 部分退款成功
- 超額退款應拋出 IllegalArgumentException
- 已退款的訂單不能重複退款
- 並發退款的樂觀鎖衝突處理」

# Step 2：確認測試（此時應全部失敗）
「跑一下測試，確認都是 RED 狀態」

# Step 3：實作程式碼讓測試通過
「現在實作 RefundService.processRefund()，讓所有測試通過」

# Step 4：重構
「測試都通過了。現在重構——有沒有重複程式碼或可以抽象的地方？」

    雙代理 Code Review

    # 完成實作後，啟動 Code Review 流程

# 方式一：使用 /review 技能
# Claude Code 會從多個角度審查你的程式碼變更

# 方式二：手動指定審查角度
「以 Senior Java Developer 的身份審查這次的 git diff：
1. 是否符合 SOLID 原則？
2. 異常處理是否完整？
3. 是否有潛在的效能問題？
4. API 設計是否符合 RESTful 規範？
5. 測試覆蓋是否足夠？」
    💡 架構師觀點：TDD + AI Code Review 構成了一個持續品質迴圈。AI 寫測試確保功能正確，AI 審查確保品質達標。你的角色從「寫程式碼」轉變為「定義品質標準」和「做最終判斷」。

    📊 協作能力總覽：你能用 Claude Code 做什麼

    階段 能力 核心配置/工具 效率提升
    環境設定 跳過權限提示 permissions.allow 消除 80% 的中斷
    環境設定 自動化護欄 Hooks 零人工品質檢查
    環境設定 外部服務整合 MCP Servers 統一操作介面
    需求階段 腦力激盪 Skills: brainstorming 結構化需求探索
    設計階段 計畫模式 Plan Mode 先謀後動，減少返工
    設計階段 專案上下文 CLAUDE.md AI 自動遵守規範
    開發階段 TDD 工作流 Skills: TDD 測試先行，品質保證
    開發階段 多代理並行 Subagents 任務並行，加速 N 倍
    開發階段 背景代理 Background agents 非阻塞式工作
    開發階段 隔離環境 Git Worktree 互不干擾的並行開發
    審查階段 Code Review Skills: code-review 多角度自動審查
    部署階段 全自動模式 Auto Mode AI 自主判斷，減少打擾
    跨對話 記憶系統 Memory 知識累積，越用越聰明
    跨對話 上下文管理 /compact + Hooks 更長的有效工作時間
    日常 IDE 整合 VSCode Extension 零上下文切換
    日常 SSH 遠端 sshConfigs 隨處開發

    🎯 結語：從工具到戰友，但要是誠實的戰友

    這篇文章從 settings.json 的基礎配置出發，一路展開到 Claude Code 的完整協作生態。17 個核心能力站點分為三層：

    • 基礎設施層（第 1-8 站）：權限、Hooks、MCP、Sandbox、Worktree、環境變數、SSH、Plugins——你的「硬體配置」
    • 工作流程層（第 9-13 站）：CLAUDE.md、Plan Mode、多代理、Memory、溝通技巧——你的「操作系統」
    • 自動化層（第 14-17 站）：Auto Mode、IDE 整合、背景代理、TDD/Code Review——你的「自動駕駛」

    但如果你只記住一件事，請記住這個：

    AI 最危險的時候不是它出錯的時候——是它看起來沒出錯的時候。

    所有的配置、Hooks、自動化，都是為了讓協作更高效。但高效的前提是正確。而正確的前提是你敢對 AI 的輸出踩煞車，問它：「你跳過了什麼？」

    不要追求「完美的 Prompt」。不要花時間研究該給 AI 什麼角色。把那些時間拿來：

    1. 描述你的痛點（而不是指定解法）
    2. 讓 AI 問你問題（而不是你猜它需要什麼）
    3. 在「看起來差不多」的時候多問一句（而不是直接 GO）
    4. 把失敗經驗告訴它（而不是只給它成功案例）

    好的人機協作不是人學會說機器的語言，而是建立一個雙方都誠實的溝通環境。

    你配置 Claude Code 的方式，反映的不只是技術能力——更是你對「什麼是好的協作」的理解。

    本文基於 Claude Code 2026 年 3 月版本撰寫，並包含真實的人機協作反思。所有配置範例均經過實戰驗證。

  • 【深度解析】2026 Agentic Coding Trends Report — 資深架構師的全面剖析與實戰指南

    Anthropic 於 2026 年初發布了《2026 Agentic Coding Trends Report》，提出了 8 大趨勢預測。作為一名在企業級系統架構領域深耕多年的架構師，我將逐一拆解每個趨勢，結合實際的代理操作經驗，為你呈現這份報告背後的深層意涵。

    🏗️ 基礎趨勢：地殼級的轉變

    趨勢 1：軟體開發生命週期（SDLC）將劇烈改變

    架構師視角

    這不只是「AI 幫你寫 code」這麼簡單。報告指出，從機器碼到組合語言、從 C 到現代高階語言，每一層抽象都在縮短人類思維與機器執行之間的距離。而 Agentic AI 是這條演化路線上最新的一步——人機對話式程式開發。

    作為架構師，我看到的核心轉變是：工程師的角色從「實作者」變成「指揮者」。這就像軍隊中從士兵升為指揮官——你不再親自衝鋒陷陣，而是制定戰略、分配資源、審查成果。

    報告特別提到一個關鍵數據：工程師約 60% 的工作使用 AI，但只有 0-20% 能完全委派。這說明了一個事實——AI 是協作者，不是替代者。你仍然需要深厚的工程知識來判斷 AI 產出的品質。

    實戰操作：如何用 Coding Agent 重塑你的 SDLC

    場景一：快速上手陌生程式碼庫

    報告指出新人上手時間將從數週壓縮到數小時。以下是實際操作方式：

    # 使用 Claude Code 探索陌生程式碼庫
# 步驟 1：讓代理理解整體架構
$ claude "分析這個專案的整體架構，包括主要模組、依賴關係、資料流向"

# 步驟 2：針對特定模組深入了解
$ claude "解釋 src/auth/ 目錄下的認證機制，包括 token 生命週期和刷新策略"

# 步驟 3：理解業務邏輯
$ claude "追蹤一個訂單從建立到完成的完整流程，列出涉及的所有服務和資料表"

    場景二：架構決策輔助

    # 讓代理幫你評估架構方案
$ claude "我們正在考慮將單體應用拆分為微服務。
分析目前的程式碼耦合度，識別可以獨立拆分的邊界上下文（Bounded Context），
並評估每個拆分方案的風險和收益"

# 代理會：
# 1. 掃描所有模組間的依賴關係
# 2. 識別高耦合和低耦合的邊界
# 3. 提出具體的拆分建議和遷移路徑

    架構師建議：建立一份「AI 委派矩陣」——明確定義哪些任務適合完全委派、哪些需要協作完成、哪些必須人工處理。例如：

    • 完全委派：單元測試撰寫、程式碼格式化、簡單 CRUD API、文件生成
    • 協作完成：複雜業務邏輯、效能優化、資料庫 schema 設計
    • 人工主導：架構決策、安全審計、合規性審查、系統設計

    ⚡ 能力趨勢：代理能做什麼

    趨勢 2：單一代理演化為協調團隊

    架構師視角

    這是我認為最具顛覆性的趨勢。報告中提到 Fountain 公司透過階層式多代理協調（Hierarchical Multi-Agent Orchestration）實現了 50% 更快的篩選速度和 2 倍的候選人轉化率。

    從架構角度來看，Multi-Agent 系統本質上就是分散式系統設計——這正是我們架構師的核心能力。想像一下：每個 Agent 就是一個微服務，擁有獨立的 context window（類似獨立的記憶體空間），透過 Orchestrator（類似 API Gateway 或 Message Broker）進行協調。

    關鍵的架構模式有三種：

    1. Orchestrator Pattern（編排模式）：一個中央代理分配任務、收集結果
    2. Pipeline Pattern（管線模式）：代理們串聯處理，每個處理完交給下一個
    3. Swarm Pattern（群體模式）：多個代理平行處理，最後彙整結果

    實戰操作：建構多代理工作流

    場景：用多代理系統進行完整的 Feature 開發

    # 使用 Claude Code 的 subagent 機制
# 主代理（Orchestrator）接收需求後，分派給專業子代理

# Agent 1: 架構分析代理
$ claude "作為架構分析代理，分析「新增用戶通知系統」這個需求，
識別需要修改的模組、新增的介面、以及對現有系統的影響"

# Agent 2: 測試代理 — 平行撰寫測試
$ claude "作為測試代理，為用戶通知系統撰寫完整的測試案例，
包括單元測試、整合測試、邊界條件測試"

# Agent 3: 實作代理 — 根據架構分析進行開發
$ claude "根據以下架構分析結果，實作用戶通知系統的核心模組..."

# Agent 4: 安全審查代理
$ claude "審查以下程式碼的安全性，檢查 OWASP Top 10 漏洞，
特別關注輸入驗證、SQL Injection、XSS 防護"

    進階：使用 Claude Agent SDK 建構自動化多代理系統

    # 使用 Claude Agent SDK 建構 Multi-Agent Pipeline
from claude_agent_sdk import Agent, Orchestrator

# 定義專業代理
architect_agent = Agent(
    role="architect",
    system_prompt="你是資深架構師，負責分析需求並產出技術設計文件",
    tools=["file_read", "codebase_search"]
)

test_agent = Agent(
    role="tester",
    system_prompt="你是測試工程師，負責撰寫全面的測試案例",
    tools=["file_write", "test_runner"]
)

impl_agent = Agent(
    role="implementer",
    system_prompt="你是實作工程師，根據設計文件和測試案例進行開發",
    tools=["file_write", "file_edit", "bash"]
)

reviewer_agent = Agent(
    role="reviewer",
    system_prompt="你是 Code Reviewer，負責品質和安全審查",
    tools=["file_read", "security_scanner"]
)

# 建構協調器
orchestrator = Orchestrator(
    agents=[architect_agent, test_agent, impl_agent, reviewer_agent],
    workflow="sequential",  # 或 "parallel", "hierarchical"
    checkpoints=["after_design", "after_tests", "after_implementation"]
)

# 執行
result = orchestrator.run("實作用戶通知系統，支援 Email、SMS、Push 三種管道")

    架構師建議：不要一開始就追求複雜的多代理架構。先從兩個代理開始——一個負責實作，一個負責審查——建立基本的「雙人檢查」機制，再逐步擴展。

    趨勢 3：長時間運行的代理建構完整系統

    架構師視角

    報告中的 Rakuten 案例極具說服力：Claude Code 在 7 小時內自主完成了在一個 1,250 萬行程式碼庫中的複雜實作，達到 99.9% 的數值精確度。

    從架構角度來看，長時間運行的代理本質上需要解決三個核心問題：

    1. 狀態管理（State Management）：代理如何在長時間任務中維持一致的上下文？
    2. 錯誤恢復（Error Recovery）：當代理遇到錯誤時，如何回退並嘗試替代方案？
    3. 檢查點（Checkpointing）：如何設置人工介入點，確保代理沒有偏離方向？

    這些問題與我們設計分散式系統時面臨的挑戰如出一轍。Saga Pattern、Circuit Breaker、Retry with Backoff——這些架構模式都可以類比到代理系統的設計中。

    實戰操作：設置長時間運行的代理任務

    # 場景：讓代理自主重構整個模組

# 步驟 1：提供清晰的目標和邊界
$ claude "重構 src/legacy/payment/ 模組：
目標：將回調式（callback）程式碼遷移到 async/await 模式
邊界：
- 不要修改公開 API 介面
- 保持所有現有測試通過
- 每完成一個檔案就執行測試套件
- 如果測試失敗，回退該檔案的變更並報告問題
檢查點：每處理 5 個檔案暫停，等待我的確認"

# 步驟 2：利用 CLAUDE.md 提供長期上下文
# 在專案根目錄建立 CLAUDE.md，讓代理記住專案規範

# 步驟 3：使用 Git Worktree 隔離工作
$ git worktree add ../payment-refactor feature/payment-async
$ cd ../payment-refactor
$ claude "開始重構工作..."

    架構師建議：為長時間代理任務設計「護欄（Guardrails）」——明確定義代理不能做的事情比定義它應該做什麼更重要。這就像 Kubernetes 的 Resource Limits 一樣，防止代理失控。

    趨勢 4：人類監督透過智慧協作擴展

    架構師視角

    報告揭示了一個「協作悖論」：工程師 60% 的工作使用 AI，但只有極小比例能完全委派。這不是 AI 能力不足，而是信任需要逐步建立。

    從系統設計角度，這就是漸進式信任模型（Progressive Trust Model）：

    • Level 0 – 監控模式：代理執行，人類逐行審查（適合初期導入）
    • Level 1 – 抽查模式：代理執行，人類抽樣審查（適合建立信任後）
    • Level 2 – 異常模式：代理執行 + 自我審查，只有異常才通知人類
    • Level 3 – 自主模式：代理全自主執行，人類只在策略層介入

    實戰操作：建立智慧監督機制

    # 利用 Claude Code 的 Hooks 機制建立自動化審查

# 在 .claude/settings.json 中設定 hooks
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npm run lint --fix && npm test -- --bail"
      }
    ],
    "PostCommit": [
      {
        "command": "npm run security-audit"
      }
    ]
  }
}

# 這樣每次代理修改程式碼，都會自動：
# 1. 執行 lint 檢查
# 2. 執行測試
# 3. 提交時執行安全掃描
# 形成自動化的品質護欄

    場景：使用代理審查代理的產出

    # Agent A: 實作功能
$ claude "實作用戶匯出功能，支援 CSV 和 Excel 格式"

# Agent B: 審查 Agent A 的產出（獨立 context，避免偏見）
$ claude "請審查以下程式碼變更（git diff），從以下角度：
1. 安全性：是否有 injection 風險？大檔案是否會 OOM？
2. 效能：匯出 100 萬筆資料時的記憶體和時間複雜度？
3. 可維護性：是否符合專案既有的設計模式？
4. 邊界條件：空資料、特殊字元、併發匯出等情況？"

    架構師建議：建立「代理信任儀表板」——追蹤代理產出的品質指標（測試通過率、Code Review 修改率、Bug 回報率），用數據驅動你的信任等級調整。

    趨勢 5：代理編程擴展到新領域和新用戶

    架構師視角

    報告指出 AI 正在打破「寫程式的人」和「不寫程式的人」之間的界線。這對架構師來說意味著一個巨大的設計挑戰：如何設計系統讓非技術人員也能安全地進行自動化？

    想像一下你的法務團隊用 AI 建立了合約審查自動化、行銷團隊建立了 A/B 測試分析管線、HR 建立了招聘數據儀表板——這些都直接連接到你的核心系統。沒有良好的架構，這就是一場災難。

    實戰操作：為非技術團隊建立安全的代理環境

    # 場景：讓數據分析師用代理進行資料分析

# 方式 1：提供受限的 Claude Code 環境
# 建立專用的 CLAUDE.md 限制代理行為
# 允許：讀取 /data/ 目錄、執行 Python 腳本、產生圖表
# 禁止：修改任何程式碼、存取生產資料庫、安裝新套件

# 方式 2：使用 MCP (Model Context Protocol) 提供安全的 API 存取
{
  "mcpServers": {
    "company-data": {
      "command": "node",
      "args": ["mcp-server/data-access.js"],
      "env": {
        "DB_ROLE": "readonly",
        "MAX_ROWS": "10000"
      }
    }
  }
}

    架構師建議：為每個非技術團隊的代理使用場景設計「沙盒（Sandbox）」。就像你不會給實習生 production 的 root 權限一樣，非技術人員的代理也需要明確的權限邊界。使用 Least Privilege 原則，只給代理完成任務所需的最小權限。

    📊 影響趨勢：代理將改變什麼

    趨勢 6：生產力提升重塑軟體開發經濟

    架構師視角

    報告中最引人注目的數據是：約 27% 的 AI 輔助工作是「原本不會做的事」。這不只是效率提升，而是價值創造。

    從架構師角度，我把這稱為「技術債務清算窗口」。過去那些因為「沒時間」而累積的技術債——老舊的 API 版本、缺失的測試、過時的文件、效能瓶頸——現在都可以系統性地被代理消滅。

    報告提到三個乘數效應（Three Multipliers）：代理能力提升 × 協調改進 × 人類經驗 = 指數級加速。這不是線性增長，而是複合增長。就像 DevOps 革命一樣，三者相互增強。

    實戰操作：系統性消滅技術債

    # 場景：用代理批量處理技術債

# 步驟 1：讓代理掃描並分類技術債
$ claude "掃描整個程式碼庫，識別以下類型的技術債：
1. 已廢棄的 API 調用（deprecated warnings）
2. 缺少測試覆蓋的關鍵路徑
3. 硬編碼的配置值
4. 重複的程式碼（DRY 違反）
5. 不一致的錯誤處理模式
按嚴重程度和修復成本排序，產出優先級清單"

# 步驟 2：逐項自動修復
$ claude "根據優先級清單，從最高優先級開始：
- 每修復一項，執行完整測試套件
- 每項修復獨立一個 commit
- 如果修復可能影響其他模組，標記為需要人工審查"

    架構師建議：建立「20% 代理時間」制度——每個 Sprint 撥出 20% 的代理運算資源專門處理技術債。用代理來做那些人類「知道該做但沒時間做」的事。

    趨勢 7：非技術用例擴展至全組織

    架構師視角

    報告中 Anthropic 自家法務團隊的案例最具說服力：一位沒有程式碼經驗的律師用 Claude Code 建立了自助服務工具，將行銷審查周轉時間從 2-3 天縮短到 24 小時。

    Zapier 更是達到了 89% 的全組織 AI 採用率，部署了 800+ 個內部 AI 代理。

    作為架構師，這意味著你需要開始思考「代理治理（Agent Governance）」：誰可以建立代理？代理可以存取哪些系統？如何追蹤和審計代理的行為？代理出錯時的責任歸屬？

    實戰操作：建構組織級代理平台

    # 架構建議：建立內部的 Agent Platform

# 1. 定義代理模板（Agent Templates）
# marketing-agent-template.yaml
name: marketing-automation-agent
permissions:
  read: [marketing-data, analytics-api]
  write: [marketing-reports, draft-content]
  execute: [data-analysis-scripts]
  forbidden: [production-db, source-code, deployment]
resource_limits:
  max_tokens_per_day: 1000000
  max_api_calls: 500
audit:
  log_all_actions: true
  alert_on: [data-access, external-api-call]

# 2. 建立自助服務入口
# 非技術人員透過 Web UI 與代理互動
# 所有操作都在沙盒環境中執行

# 3. 監控儀表板
# 追蹤全組織的代理使用情況：
# - 各部門使用量和成本
# - 代理產出的品質指標
# - ROI 分析（節省的人力時間 vs 代理成本）

    架構師建議：把「代理治理」視為與「資料治理」同等重要的架構議題。建立 Agent Center of Excellence (ACoE)，制定組織級的代理使用政策、安全標準和最佳實踐。

    趨勢 8：雙重用途風險需要安全優先架構

    架構師視角

    這是最被低估但最重要的趨勢。報告指出：同樣的 AI 能力既能強化防禦，也能助長攻擊。

    從架構角度，這意味著安全不再是事後補救，而必須是設計時的第一考量（Security by Design）。當任何工程師都能用 AI 進行深度安全審查時，攻擊者也能用同樣的 AI 尋找漏洞。

    關鍵的架構原則：

    • Zero Trust Architecture：不信任任何內部或外部的代理輸出
    • Defense in Depth：多層防禦，即使一層被突破仍有保護
    • Shift Left Security：在開發早期就嵌入安全檢查

    實戰操作：用代理建立安全防線

    # 場景 1：自動化安全審查管線
# 在 CI/CD Pipeline 中嵌入 AI 安全審查
name: AI Security Review
on: [pull_request]
jobs:
  security-review:
    steps:
      - name: AI Security Scan
        run: |
          claude "審查這個 PR 的所有變更：
          1. OWASP Top 10 漏洞掃描
          2. 硬編碼的密鑰或憑證
          3. SQL/NoSQL Injection 風險
          4. XSS 和 CSRF 防護
          5. 權限提升風險
          6. 敏感資料洩漏
          以 SARIF 格式輸出結果"

# 場景 2：用代理進行威脅建模
$ claude "對以下系統架構進行威脅建模（STRIDE 方法）：
- 前端：React SPA
- API Gateway：Kong
- 後端：Spring Boot 微服務群
- 資料庫：PostgreSQL + Redis
- 訊息佇列：Kafka
- 部署：Kubernetes on AWS"

# 場景 3：AI 紅藍對抗
# 用一個代理扮演攻擊者（Red Team）尋找漏洞
# 另一個代理扮演防禦者（Blue Team）修補漏洞

    架構師建議：建立「AI 紅藍對抗」機制——用一個代理扮演攻擊者尋找漏洞，另一個代理扮演防禦者修補漏洞。這種持續的對抗演練能顯著提升系統安全性。

    🎯 我的行動建議：2026 年架構師優先事項

    綜合以上 8 大趨勢，我給出以下具體的行動清單：

    立即行動（本月）

    1. 建立 CLAUDE.md：為每個專案建立代理上下文文件，定義程式碼規範、禁止事項、測試要求
    2. 設定 Hooks：配置自動化品質護欄，確保代理每次修改都通過基本檢查
    3. 導入雙代理審查：一個代理寫程式碼，另一個代理審查，建立基本的品質保障

    短期規劃（本季）

    1. 建立 AI 委派矩陣：明確定義團隊中哪些任務適合委派給代理
    2. 啟動技術債清理專案：利用代理系統性處理積壓的技術債
    3. 設計代理安全框架：定義代理的權限邊界、審計機制、異常處理

    中期布局（今年）

    1. 建構多代理協調系統：根據團隊需求設計 Orchestrator 架構
    2. 推動非技術團隊採用：為業務團隊建立安全的代理沙盒環境
    3. 建立 Agent Governance 體系：制定組織級的代理使用政策和治理框架

    結語

    這份報告的核心訊息很清楚：2026 年的軟體開發正在從「寫程式碼」轉向「指揮寫程式碼的代理」。但這不是要取代工程師——恰恰相反，它要求工程師具備更高層次的思考能力：架構設計、系統思維、品質判斷、安全意識。

    作為架構師，我們正處於一個前所未有的機遇期。那些能夠設計良好的代理協作架構、建立有效的人機協作模式、並在組織層面推動代理治理的架構師，將成為這場變革的引領者。

    最後的忠告：不要等到完美才開始。今天就打開 Claude Code，給它一個你一直拖著沒做的重構任務，開始建立你的代理協作經驗。實踐出真知。

    本文基於 Anthropic《2026 Agentic Coding Trends Report》撰寫。報告原文共 18 頁，涵蓋基礎趨勢、能力趨勢、影響趨勢三大類別共 8 個趨勢預測。

  • 舊系統不死，AI 讓它進化：不重寫也能持續成長

    重點摘要

    • 舊系統不是問題，缺乏 AI 輔助才是問題——AI 讓「不重寫、持續演進」成為可行選項
    • 歷史證明：超過 80% 的「重寫計畫」以失敗或兩個系統都要維護收場
    • AI 最確定的價值是讀懂舊代碼、補文件、補測試，讓團隊敢繼續開發
    • 「AI 能不能讓大規模翻新變安全」——這是尚待驗證的命題，不宜過度樂觀

    你的公司有一套跑了十年的系統。它能動，它撐起了整個業務，但沒有人敢碰它。文件不齊、邏輯散落在各處、原始開發者早就離職了。每次有人提議「重寫」，討論就會陷入沉默——因為大家心裡都知道，這條路走過很多次，沒幾次是成功的。

    AI 的出現，讓這個困境有了新的解法。但不是你想像中的那種解法。

    為什麼重寫這麼難？歷史給了殘酷的答案

    軟體界有個著名的現象叫做 Second System Effect（第二系統效應），由《人月神話》作者 Fred Brooks 提出：工程師在重寫時，往往會把所有「本來想做卻沒做」的功能都塞進去，結果新系統比舊系統更複雜、更難維護。

    但更根本的問題是：舊系統裡有隱藏的業務邏輯，它們沒有寫在文件裡，只存在於代碼的行為中——某個奇怪的判斷式、某個例外處理、某個只在特定情境才觸發的路徑。這些邏輯，是十年來無數個「為什麼這樣做？」的答案。

    重寫計畫的典型失敗模式

    • 兩個系統並行期拉太長：新舊系統同時維護，工程師精力分散，bug 在兩邊都出現
    • 上線那天發現漏了邏輯：舊系統某個角落的行為，新系統根本沒有對應
    • 商業壓力中斷重寫：計畫進行到一半，業務需求改變，只能把新舊系統黏在一起
    • 重寫後反而更慢：新架構雖然「漂亮」，但少了十年累積的效能優化細節

    這不是悲觀，這是現實。重寫不是不可能，但它的成功率遠低於大多數人的預期。在 AI 出現之前，面對舊系統，企業只有兩條路：硬撐，或者賭一把。

    AI 帶來了第三條路：輔助成長

    AI 最確定的價值，不是幫你重寫系統，而是讓「不重寫、持續演進」這件事變得可持續。

    過去，舊系統的最大問題不是代碼本身，而是「沒有人理解它」。原始開發者離職了，知識沒有傳承；文件過時了，沒有人有時間更新；要改一個功能，必須花三天理解上下文，才敢動一行代碼。

    AI 改變了這個方程式。

    AI 能為舊系統做什麼？

    挑戰 過去的困境 AI 輔助後
    理解舊代碼 要花幾天甚至幾週閱讀 AI 幾分鐘內產出架構圖和流程說明
    補充文件 沒時間寫、寫了也快過時 AI 根據現有代碼生成，每次修改後更新
    補充測試 舊系統通常 0 測試，改動沒有安全網 AI 針對現有行為補寫測試，改動有保護
    修復 bug 怕改了 A 壞了 B，只敢最小化改動 AI 追蹤影響範圍，降低連帶破壞風險
    新人上手 要跟著老人學幾個月才敢動 AI 隨時解釋任何一段代碼的邏輯和背景
    新增功能 不知道該插在哪裡，怕破壞現有邏輯 AI 建議最小侵入式的擴充點

    實際做法：AI 如何輔助舊系統成長

    第一步：讓 AI 讀懂系統，產出活的文件

    不要急著改代碼。第一件事是讓 AI 理解現有系統，然後把理解結果固化成文件。

    # 讓 AI 讀整個 codebase，產出架構說明
# 在 Claude Code 中，直接描述你的需求：

「請閱讀這個專案的所有代碼，並產出：
1. 系統架構圖（模組與模組之間的關係）
2. 核心業務流程說明（從使用者角度描述主要流程）
3. 高風險區域列表（邏輯最複雜、最不敢動的地方）
4. 技術債清單（有哪些地方明顯需要改善）」

    這份文件不是給外部人看的，是給你的團隊每天使用的工作手冊。它會隨著系統改動而更新——這一點很重要，因為過去文件之所以沒用，是因為沒有人有時間維護它。AI 讓維護文件的成本降低了 90%。

    第二步：為現有行為補測試，建立安全網

    舊系統的問題不是「代碼爛」，而是「沒有測試保護」。任何一個修改都是在沒有安全網的情況下走鋼絲。

    AI 可以閱讀現有代碼，理解它的行為，然後為這些行為寫測試——即使這些行為從來沒有文件。

    # 範例：讓 AI 為現有函式補測試
「這個函式 calculateDiscount() 已經跑了八年，
請分析它的所有分支條件，為每個分支寫一個測試案例，
包括正常情況、邊界值和異常情況。
不要改動現有邏輯，只補充測試。」

    有了測試，團隊才敢改動。改動有安全網，系統才能持續演進而不是不斷累積技術債。

    第三步：最小侵入式地新增功能

    新增功能不等於重構整個模組。AI 擅長找到「最小侵入式的擴充點」——在不動現有邏輯的前提下，把新功能插進去。

    這個原則來自 Open/Closed Principle（開放封閉原則）：對擴充開放，對修改封閉。即使舊系統沒有遵循這個原則，AI 也可以建議如何在外圍包一層，讓新功能不影響舊邏輯。

    第四步：漸進式現代化，而非大爆炸式重寫

    如果真的有部分需要改善，AI 輔助的方式是：一次只動一個模組，改完之後讓它穩定跑一段時間，確認沒有問題再動下一個。

    這不是「重寫」，這是「漸進式現代化」。兩者的關鍵差異：

    重寫 漸進式現代化
    範圍 全部 一次一個模組
    風險 集中在上線日 分散，每步都可以回滾
    業務中斷 長期並行維護兩個系統 系統持續運作，局部更新
    AI 的角色 「幫我重新實作這一切」 「幫我安全地改善這一塊」

    那麼，「重寫」這條路呢？

    這是一個需要誠實面對的問題。

    過去的答案很清楚：重寫計畫成功率低，風險高，通常不是好選擇。大多數成功的案例，仔細看都是「漸進式替換」而不是「一次性重寫」。

    AI 會改變這個答案嗎？

    這是一個尚待驗證的命題。AI 確實讓理解舊系統更容易，讓知識遷移成本降低，理論上應該讓重寫的準備工作做得更完整。但「做得更完整的準備」不等於「執行時不會出問題」。隱藏的業務邏輯、時序問題、效能細節——這些在代碼裡只有在跑了幾百萬筆資料之後才會浮現。

    更誠實的說法是：

    • AI 讓「輔助成長」這條路變得可行——這是現在就可以驗證的事
    • AI 讓「重寫」變得更安全——這是有可能的，但還需要更多實際案例來驗證
    • AI 能取代「漸進式替換」的謹慎原則——不太可能，這個原則的價值在於限制風險暴露，而不是技術能力

    所以，如果有人告訴你「有了 AI，重寫就不危險了」——保持懷疑。如果有人告訴你「AI 讓你不需要擔心舊系統的技術債了」——同樣保持懷疑。

    如何判斷你的系統需要什麼？

    面對舊系統，用這個框架來判斷方向：

    優先考慮 AI 輔助成長，如果：

    • 系統仍然在提供商業價值，只是難以維護
    • 核心業務邏輯複雜，沒有人完整理解
    • 團隊規模小，無法支撐兩個系統並行
    • 業務需求變化頻繁，不能停下來等重寫完成

    可以考慮漸進式替換（不是重寫），如果：

    • 某個模組已經明顯成為瓶頸，且邊界清晰
    • 有足夠的測試保護現有行為
    • 可以部署影子流量，讓新舊模組並行驗證
    • 有明確的回滾機制

    謹慎考慮大規模重寫，只有當：

    • 現有系統在技術上已經無法繼續擴充（不只是難，而是真的不可能）
    • 有足夠的資源支撐至少 18 個月的並行期
    • 有完整的行為規格文件（或 AI 幫你產出的等效文件）
    • 組織願意接受在過渡期期間功能停滯

    結語：舊系統不是問題，缺乏支援才是

    回到最初的問題：那套跑了十年的系統，它的問題不是年齡，而是孤立。沒有人理解它，沒有測試保護它，沒有文件說明它，改動它需要承擔巨大的個人風險。

    AI 能做的，是讓這個系統不再孤立。它可以成為每個工程師的「老前輩」——隨時解釋任何一段邏輯，隨時分析改動的影響，隨時生成測試保護現有行為。

    這不是重寫的故事，這是陪伴成長的故事。

    至於重寫——如果未來真的需要，AI 會讓你準備得更充分。但那是另一個故事，而且它的結局還沒有寫完。

  • 10 年舊系統如何安全導入 AI 開發：Strangler Fig 遷移方法論

    重點摘要

    • 10 年的舊系統能跑就是最有價值的資產，不要試圖先修好再遷移
    • 核心方法論：Strangler Fig 模式 — 新軌道在旁邊長起來，舊系統自然退場
    • AI 第一件事不是寫 code，而是讀懂 10 年的系統邏輯，再動手
    • 四個階段：快照現況 → 建平行新軌 → 一次搬一個服務 → 封存舊系統

    你的系統跑了 10 年。它很髒、沒有文件、CI/CD 靠手動、密碼可能在 .env 裡或者在某個工程師的腦袋裡。但它能跑，而且在服務真實的用戶。

    現在你想引入 AI 輔助開發，想現代化整個工作流。問題來了：要從哪裡開始？ 要先把舊的修乾淨，還是直接用新方法？

    錯誤的答案是：「先把舊的修好。」正確的答案是：不要動正在跑的東西，在旁邊建一條新軌道。

    為什麼「先修好再用新方法」行不通？

    這個直覺很自然，但在實際工程上幾乎都會失敗，原因有三：

    1. 無法停止開發等你修 — 業務不會暫停，新需求還是會進來，你邊修邊開發，舊問題永遠追不完
    2. 「修好」的定義會不斷移動 — 一開始說只要加 .gitignore，結果發現歷史有密碼，要 filter-repo，然後發現測試覆蓋率是零…沒有終點
    3. 你在修一個不完全理解的系統 — 10 年的系統有太多隱性知識，修的過程中很容易把「能跑的」改成「不能跑的」

    工程界有一個著名的模式專門解決這個問題，叫做 Strangler Fig（絞殺榕）模式。

    Strangler Fig 模式：不砍舊樹，讓新藤蔓長過去

    絞殺榕是一種熱帶植物。它的種子落在老樹上，慢慢向下長出根，包住舊樹，最後舊樹自然退場，絞殺榕站立在原位。整個過程中，舊樹從未停止「提供支撐」，直到新系統完全就緒。

    應用到 DevOps 遷移：

    ❌ 錯誤思維：
舊系統（停機）→ 修好 → 接新流程 → 恢復服務

✅ 正確思維（Strangler Fig）：
舊系統（持續運行，不動）
    ↓
新軌道在旁邊建立（不影響舊系統）
    ↓
一次搬一個服務，驗證後切換流量
    ↓
所有服務搬完，舊系統自然退場

    關鍵洞察：能跑的系統是你最有價值的資產，不是問題的來源。遷移的目標是「讓它繼續跑，同時讓新系統在旁邊成長」，不是「讓它停下來修好再說」。

    四個階段的完整遷移方法論

    階段一：快照現況（不動任何東西）

    第一步不是改 code，不是設定 CI/CD，而是把「現在是怎麼跑起來的」完整記錄下來。這份快照是整個遷移過程的地基。

    為什麼要快照？因為在 10 年的系統裡，repo 裡的 .env 可能是舊的，文件可能是錯的，只有正在跑的進程才是真相：

    # 從正在跑的容器抽出真實的環境變數
docker inspect <container_name> \
  --format='{{range .Config.Env}}{{println .}}{{end}}' \
  > /tmp/real-env-snapshot.txt

# 或直接讀進程的環境變數
cat /proc/$(pgrep java)/environ | tr '\0' '\n' | grep -E "DB_|API_|SECRET_"

# K8s 環境
kubectl get pods -n production -o name | while read pod; do
  echo "=== $pod ==="
  kubectl exec $pod -n production -- env 2>/dev/null
done > /tmp/real-k8s-env-snapshot.txt

    同時盤點服務清單和依賴關係：

    # 有哪些服務在跑
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# 服務之間怎麼通訊
docker network inspect bridge

# 對外開放哪些 port
ss -tlnp | grep LISTEN

    這個階段的產出是一份真實架構圖和一份真實密碼清單（妥善保管，不進任何 repo）。

    階段二：AI 讀懂你的系統

    這是大多數人忽略的步驟，也是決定 AI 協作能否成功的關鍵。

    AI 第一件事不是寫 code。

    在 AI 動手之前，它需要讀你 10 年的系統。這個過程大概需要幾天，但會產出你可能從未有過的東西：

    AI 讀完後的產出 為什麼重要
    系統架構圖 你們可能自己也沒有，新人上手和遷移規劃的基礎
    模組依賴關係 知道改哪個地方會影響哪些服務
    高風險區域標記 「這段 code 10 個人改過，有 3 個已知 bug 的修復」
    技術債清單（按影響排序） 知道先解決什麼，不是看到髒的就改
    新人上手文件 從 code 反推出來，不需要老工程師口傳

    這個階段同樣不動任何 code。AI 只是閱讀和理解。等到真正開始寫新功能時，AI 已經知道你的系統慣例是什麼、有哪些地雷不能踩。

    階段三：建立平行的新軌道

    新建一個乾淨的 repo，在旁邊建立完整的現代化工作流，舊 repo 繼續照舊運作：

    舊 GitLab repo（繼續跑，不動）
     │
     │  正在服務用戶的系統
     │
新 repo（乾淨起點）
     │
     ├─ 正確的 .gitignore（.env 全部排除）
     ├─ CI/CD pipeline（gitleaks + build + sign）
     ├─ K8s Secrets（從快照搬進來）
     └─ Branch Protection Rules

    把真實密碼從快照搬到 K8s Secrets（不是從舊 repo 搬，是從正在跑的進程抽出來）：

    # 從快照建立 K8s Secrets
kubectl create secret generic app-prod-creds \
  --from-literal=DB_PASSWORD="$(grep DB_PASSWORD /tmp/real-env-snapshot.txt | cut -d= -f2)" \
  --from-literal=SHOPEE_KEY="$(grep SHOPEE_KEY /tmp/real-env-snapshot.txt | cut -d= -f2)" \
  -n production

# 建立完成後，安全刪除快照
shred -u /tmp/real-env-snapshot.txt

    階段四：一次搬一個服務

    這是遷移的主體。原則是：每次只搬一個服務，驗證通過才搬下一個。

    服務搬移的優先順序建議：

    優先順序 選擇原則 理由
    第一批 流量最小的非核心服務 風險最低，可以放心試錯
    第二批 獨立性高、依賴少的服務 不會牽一髮動全身
    最後 核心業務邏輯（訂單、付款） 等前幾批證明新流程可靠後再動

    每個服務的搬移步驟：

    1. AI 在新 repo 重寫該服務的乾淨版本（理解舊 code 後重寫，不是 copy paste）
    2. Jenkins 構建新鏡像，部署到 Staging
    3. 用影子流量驗證新舊行為一致（新舊同時收請求，比對回應）
    4. 確認無誤，切換這個服務的流量到新系統
    5. 觀察 24-48 小時
    6. 舊服務下線

    影子流量驗證（用 nginx 實現，不影響用戶）：

    # nginx 配置：新舊同時收請求，比對行為
location /api/orders {
    mirror /mirror-new;       # 複製請求到新系統
    proxy_pass http://old-api; # 用戶實際收到舊系統的回應
}

location = /mirror-new {
    internal;
    proxy_pass http://new-api;  # 新系統的回應只寫 log，不回傳用戶
}

    AI 在整個過程中的實際角色

    理解了遷移方法論後，AI 在這個過程中的職責非常清楚：

    AI 能做（且做得很好）：
  ✅ 讀 10 年的舊 code，產出架構文件
  ✅ 識別技術債，按優先順序排列
  ✅ 用「符合你們系統慣例」的方式寫新功能
  ✅ 在 feature branch 開發，開 MR，等你 review
  ✅ 補測試（補現有 code 的測試覆蓋率）
  ✅ Debug（分析 log，找根因）
  ✅ 在新服務和舊系統的接縫處寫 adapter

AI 不能做（也不應該做）：
  ❌ 直接 push 到 main 或 production branch
  ❌ 決定什麼時候切換流量
  ❌ 接觸任何密碼或 production secrets
  ❌ 在沒有充分理解舊系統的情況下動手

    一個典型的 AI 協作對話長這樣：

    你：「我要加一個批次出貨的功能」

AI：「讓我先讀一下現有的出貨相關 code...
     我看到 OrderService.java 的 shipOrder()
     和 ShipmentRepository，還有一個舊的
     BatchJob 在 legacy/ 目錄。

     注意：legacy/BatchJob 有個已知的
     transaction 問題（commit a3f2c1b 的修復紀錄），
     新功能要避開。

     建議的實作方向是...你確認嗎？」

你：「方向對，去做吧」

AI：「好，我開 feature/batch-shipment，
     預計改動：
     - 新增 BatchShipmentService（核心邏輯）
     - 修改 OrderController（加 API endpoint）
     - 不動 legacy/ 目錄
     
     完成後開 MR 給你 review」

    AI 因為讀過 10 年的系統，不會做出「不符合你們慣例」的 code，也不會踩進已知的地雷。

    最常遇到的三個現實問題

    問題一：「不知道哪個 .env 是現在真正在用的」

    10 年的系統通常有多個 .env 版本，有的是舊的，有的是工程師自己改過的。以正在跑的進程為準，不要相信文件：

    # 找到 Java 進程真正使用的環境變數
cat /proc/$(pgrep java)/environ | tr '\0' '\n' | grep -E "DB_|API_|SECRET_"

# 不要用
cat .env  # 這可能是 6 個月前的版本

    問題二：「團隊還在開發，不能凍結」

    不需要凍結。舊 repo 繼續用，新 repo 並行開發。重要的 bugfix 透過 cherry-pick 同步：

    舊 repo: feature → dev → main（繼續照舊）
              │
              └─ cherry-pick 重要修復
                      │
新 repo:              └─ feature → dev → main（新流程）

    問題三：「歷史 commit 有密碼怎麼辦」

    分兩步處理：

    1. 立即輪換所有洩露的密碼 — 因為 GitHub/GitLab 可能已有快取，這一步不能等
    2. 舊 repo 等到遷移完成後再 archive — 不需要現在重寫歷史，新 repo 一開始就是乾淨的

    注意：很多人以為 git rm --cached .env 就安全了，但舊 commit 裡的內容仍然可以被 git show <old-commit>:.env 讀出。唯一的技術修復是 git filter-repo，但遷移方法論讓你可以跳過這一步——因為所有新開發都在新的乾淨 repo 上進行。

    時間軸規劃

    時間 工作 風險
    第 1 週 快照現況、輪換外部 API Key、AI 開始讀系統 零（不動任何 code）
    第 2-4 週 建新 repo、CI/CD pipeline、K8s Secrets、第一個服務搬過去 低（影子流量驗證）
    第 1-3 個月 逐服務遷移，每個驗證 24-48 小時後才繼續 中（每次只影響一個服務）
    遷移完成後 舊 repo archive、完整安全強化（RBAC、Audit Log、鏡像簽名） 低（新系統已穩定）

    決策樹：你現在該從哪裡開始

    你的系統現在能跑嗎？
  │
  ├─ 能跑 → 用 Strangler Fig 模式（本文的方法）
  │           │
  │           ├─ 步驟 1：快照現況（本週就做）
  │           ├─ 步驟 2：AI 讀系統（同步進行）
  │           ├─ 步驟 3：建新軌道（第 2-4 週）
  │           └─ 步驟 4：逐服務遷移（之後）
  │
  └─ 不能跑 → 先讓它跑起來，再回到這裡

    這套方法論的本質

    Strangler Fig 模式應用在 AI 輔助開發遷移上，核心洞察只有一個：

    「10 年的技術債是過去的決策的結果，你無法在不破壞現有價值的情況下一次消除它。但你可以選擇：從今天開始，所有新的工作都用正確的方式做。」

    舊系統是你團隊的集體記憶，AI 有能力閱讀並理解這些記憶，然後用現代化的方式繼續往前走。不需要推倒重建，也不需要凍結開發去修舊債——只需要一條平行的新軌道，和耐心地一次移動一個服務。

    想了解新軌道的 CI/CD 具體設計，可以參考上一篇文章：AI 輔助開發 CI/CD 工作流：Jenkins、K8s、ISO 27001 完整設計。

  • AI 輔助開發 CI/CD 工作流：Jenkins、K8s、ISO 27001 完整設計

    重點摘要

    • AI 只負責寫 code、提 PR，不碰版本決策和 Production 部署，人類保留最終控制權
    • 透過 Git tag 觸發 Jenkins，Staging 全自動部署、Production 手動 helm 執行，兩階段驗證才上線
    • 敏感資訊三層隔離：.gitignore → K8s Secrets → etcd 加密，密碼永遠不進 repo
    • 補齊 RBAC、Audit Log、鏡像簽名、Secrets Scan 四大安全缺口，達到 ISO 27001 合規

    AI 輔助開發越來越普遍，但大多數團隊面臨同一個問題：AI 寫的 code 要怎麼安全地上線？ 誰決定部署時機？密碼怎麼管？如果 AI 出錯了，有什麼防護網？

    本篇文章完整說明 ONEEC OMS 系統實際採用的 AI 協作工作流設計，包含完整的 User Story、Jenkins Pipeline 架構、三環境部署策略，以及通過安全審查後補齊的 RBAC、Audit Log、鏡像簽名等安全強化配置。

    核心設計理念：人類掌控節奏，AI 加速執行

    這套工作流的核心原則只有一句話：AI 是高效能的執行者，不是決策者。具體體現在以下四點：

    • AI 負責：寫 code、建 Dockerfile、提 PR、提供 Jenkins script 和 Helm chart
    • 用戶負責：code review、創建 git tag（決定版本和部署時機）、手動 helm 部署到 Production
    • 運維負責：管理 K8s Secrets、設定 Jenkins credentials、維護集群
    • 敏感資訊：密碼、API Key、SSL 憑證永遠不進入 Git repo

    完整 User Story：從需求到上線的 10 個步驟

    以下用一個真實場景說明整個流程：場景：優化訂單 API 的查詢效能。

    Step 1：AI 開發（feature branch）

    AI 從 dev 分支切出 feature branch，完成開發後推送 PR：

    # AI 執行
git checkout dev && git pull origin dev
git checkout -b feature/order-api-optimize

# 編寫程式碼...

# 本地驗證
docker-compose up -d
curl http://localhost:8080/api/orders?status=pending
# ✅ 回傳正確，效能提升 30%

# 提交並推送
git add . && git commit -m "feat(order-api): optimize query performance"
git push origin feature/order-api-optimize
# 建立 PR → dev

    Step 2：用戶 Code Review & Merge

    用戶在 GitHub UI 審查 PR：確認邏輯正確、有測試覆蓋、無敏感資訊後 approve 並 merge 到 dev。此時沒有任何自動化觸發，代碼靜靜等待部署決策。

    Step 3：用戶創建 Staging Tag → Jenkins 自動觸發

    用戶決定要部署到測試環境時，創建一個 staging-v* tag：

    # 用戶執行
git tag staging-v1.0.1
git push origin staging-v1.0.1

# GitHub Webhook → Jenkins 自動執行：
# ├─ Secrets 掃描（gitleaks）
# ├─ docker build（所有 pods）
# ├─ cosign 簽名鏡像
# ├─ docker push to registry
# ├─ helm deploy to Staging K8s（使用 values-staging.yaml）
# └─ 通知用戶：Staging v1.0.1 is live

    Step 4：用戶在 Staging 驗證

    kubectl get pods -n staging
curl https://staging-api.example.com/api/orders?status=pending
# ✅ 功能正常，效能優化生效
# ✅ 錯誤率 0%
# ✅ 回應時間 < 100ms

    Step 5：用戶創建 Production Tag → Jenkins 構建正式鏡像

    # 用戶執行（確認 Staging 無誤後）
git tag v1.0.1
git push origin v1.0.1

# Jenkins 執行：
# ├─ Secrets 掃描
# ├─ docker build（所有 pods，tag 改為 v1.0.1）
# ├─ cosign 簽名鏡像
# ├─ docker push to registry
# ├─ 生成 Helm values（不含敏感資訊）
# └─ 通知用戶：Images ready, run helm command

    Step 6：用戶手動部署到 Production

    Production 部署是整個流程中唯一純手動的步驟，這是刻意設計的——確保每一次正式上線都有人類判斷：

    # 用戶在本機執行
helm upgrade --install order-api \
  /path/to/your/prod-configs/order-api/values-prod.yaml \
  --set image.tag=v1.0.1 \
  -n production

# K8s 自動從 Secrets 注入密碼、API Key
# Kyverno 自動驗證鏡像簽名（未簽名直接拒絕）
# Deployment 完成 ✅

    Step 7：監控確認上線成功

    kubectl get pods -n production
curl https://api.example.com/api/orders?status=pending
# ✅ 正式環境驗證通過，上線成功

    三個部署環境的定義與分工

    環境 用途 部署方式 配置來源 觸發者
    Dev 本地開發驗證 docker-compose up .env.dev AI（開發時）
    Staging 測試環境（K8s） Jenkins 自動部署 values-staging.yaml（在 repo） 用戶（tag 觸發）
    Production 正式環境（K8s） 手動 helm 部署 values-prod.yaml（用戶維護）+ K8s Secrets 用戶（手動執行）

    Jenkins Pipeline 完整架構

    Jenkins Pipeline 由 GitHub Webhook（tag push）觸發，整個流程分為 6 個 Stage：

    Stage 0：Secrets 掃描（安全門控）

    這是整個 Pipeline 的第一道防線，也是最重要的安全門控。使用 gitleaks 掃描 repo 中是否含有密碼、API Key 等敏感資訊，發現即中止構建並通知安全告警。

    stage('Secrets Scan') {
    steps {
        sh '''
            gitleaks detect \
              --source . \
              --config .gitleaks.toml \
              --exit-code 1 \
              --report-format json \
              --report-path gitleaks-report.json
        '''
    }
    post {
        failure {
            sh 'sh scripts/notify-security-alert.sh ${TAG_NAME} gitleaks-report.json'
            error('❌ Secrets 掃描發現敏感資訊，構建中止！')
        }
    }
}

    Stage 1：Tag 偵測（決定部署目標）

    根據 tag 名稱判斷本次構建的部署目標：

    stage('Detect Tag') {
    steps {
        script {
            if (env.TAG_NAME =~ /^staging-v.*/) {
                env.DEPLOYMENT_ENV = 'staging'
            } else if (env.TAG_NAME =~ /^v.*/) {
                env.DEPLOYMENT_ENV = 'production'
            } else {
                error("❌ 未知 tag 格式: ${env.TAG_NAME}")
            }
        }
    }
}

    Stage 2：Build Images

    構建所有 Pod 的 Docker 鏡像。鏡像本身不含任何配置、密碼、API Key，這是配置與代碼分離的核心原則：

    #!/bin/bash
# scripts/build-docker.sh
TAG=$1

docker build -t registry.example.com/order-api:${TAG} ./simpleec-api
docker build -t registry.example.com/user-app:${TAG} ./user-app
docker build -t registry.example.com/channel-job:${TAG} ./simpleec-channel-job
# ... 所有 pods

    Stage 3：Sign Images（供應鏈安全）

    使用 cosign 為每個鏡像簽名，確保 Production 只能部署來自 Jenkins 的受信任鏡像：

    stage('Sign Images') {
    steps {
        withCredentials([file(credentialsId: 'cosign-private-key', variable: 'COSIGN_KEY')]) {
            sh 'sh scripts/sign-docker.sh ${TAG_NAME} ${COSIGN_KEY}'
        }
    }
}

# scripts/sign-docker.sh
for IMAGE in "${IMAGES[@]}"; do
    cosign sign --key "${COSIGN_KEY}" \
      --tlog-upload=false \
      "${IMAGE}"
done

    Stage 4：Push Images

    推送到 Docker Registry。Registry 啟用 Immutable Tags，同一個 tag 無法被覆蓋，確保版本不可篡改：

    stage('Push Images') {
    steps {
        withCredentials([usernamePassword(
            credentialsId: 'docker-registry-creds',
            usernameVariable: 'REGISTRY_USER',
            passwordVariable: 'REGISTRY_PASS'
        )]) {
            sh 'sh scripts/push-docker.sh ${TAG_NAME}'
        }
    }
}

    Stage 5a（Staging）：自動部署到 Staging K8s

    stage('Deploy to Staging') {
    when { expression { env.DEPLOYMENT_ENV == 'staging' } }
    steps {
        withCredentials([file(credentialsId: 'kubeconfig-staging', variable: 'KUBECONFIG')]) {
            sh '''
                helm upgrade --install order-api ./k8s/helm/order-api \
                  --values ./k8s/helm/order-api/values-staging.yaml \
                  --set image.tag=${TAG_NAME} \
                  -n staging
            '''
        }
    }
}

    Stage 5b（Production）：生成 Helm Values，通知用戶手動部署

    對於 Production tag，Jenkins 不自動部署，而是生成配置檔並通知用戶手動執行：

    stage('Generate Helm Values') {
    when { expression { env.DEPLOYMENT_ENV == 'production' } }
    steps {
        sh 'sh scripts/generate-helm-values.sh ${TAG_NAME}'
        // 生成 values-v${TAG_NAME}.yaml（不含敏感資訊）
        // 通知用戶：Images ready, run helm command
    }
}

    Helm 配置隔離：敏感資訊三層防護

    配置分為三層，層層隔離：

    第一層：values-staging.yaml（在 repo，測試配置）

    # 主機名用占位符，從 Jenkins 環境變數注入，不硬編碼內網地址
env:
  DATABASE_HOST: "${POSTGRES_STAGING_HOST}"
  DATABASE_NAME: simpleec_test
  REDIS_HOST: "${REDIS_STAGING_HOST}"
  API_LOG_LEVEL: DEBUG

    第二層：values-prod.yaml（用戶本機維護，不進 repo）

    # 用戶的私密文件，只在本機
env:
  DATABASE_HOST: postgres-prod.example.com
  API_LOG_LEVEL: WARN
  # ⚠️ 資料庫密碼不在這裡！從 K8s Secrets 注入

envFrom:
  - secretRef:
      name: database-prod-creds  # K8s Secret（運維管理）
  - secretRef:
      name: api-keys-prod        # K8s Secret（運維管理）

    第三層：K8s Secrets + etcd 加密

    # 運維在 Production K8s 上創建
kubectl create secret generic database-prod-creds \
  --from-literal=username=prod_user \
  --from-literal=password=<secure-password> \
  -n production

# K8s 預設 Secrets 以 base64 存在 etcd（並非加密！）
# 必須啟用 encryption at rest
# /etc/kubernetes/encryption-config.yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources: ["secrets"]
    providers:
      - aescbc:
          keys:
            - name: key1
              secret: <base64-encoded-32-byte-key>

    安全強化：補齊四大缺口

    原始設計經過安全審查後，發現四個必須在投產前補足的缺口：

    缺口一：K8s RBAC 未定義

    三個角色各有最小權限（文件放在 k8s/rbac/）：

    角色 允許操作 明確禁止
    Jenkins SA（staging） update/patch Deployments, get Pods 讀取任何 Secrets
    用戶（production） helm 部署相關資源 讀取業務 Secrets（DB 密碼、API Key）
    運維（production） Secrets 完整管理權 – 
    # 驗證 Jenkins SA 無法讀取 Secrets（應輸出 no）
kubectl auth can-i get secrets \
  --as=system:serviceaccount:staging:jenkins-deployer \
  -n staging

    缺口二：K8s Audit Log 未配置

    ISO 27001 A.12.4.1 要求所有敏感操作都要有日誌。以下 Audit Policy 至少記錄 Secrets 訪問和 Deployment 變更：

    # /etc/kubernetes/audit-policy.yaml
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
  - level: Metadata
    resources:
      - group: ""
        resources: ["secrets"]  # 所有 Secrets 訪問都記錄

  - level: Request
    verbs: ["create", "update", "delete", "patch"]
    resources:
      - group: "apps"
        resources: ["deployments"]

  - level: None
    users: ["system:kube-proxy"]
    verbs: ["watch", "list"]

    缺口三：鏡像簽名驗證（Kyverno 準入控制）

    確保集群只能部署來自 Jenkins 簽名的鏡像，防止鏡像替換攻擊：

    apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verify-image-signatures
spec:
  validationFailureAction: Enforce  # 未簽名鏡像直接拒絕
  rules:
    - name: check-image-signature
      match:
        any:
          - resources:
              kinds: ["Pod"]
              namespaces: ["staging", "production"]
      verifyImages:
        - imageReferences:
            - "registry.example.com/*"
          attestors:
            - count: 1
              entries:
                - keys:
                    publicKeys: |-
                      -----BEGIN PUBLIC KEY-----
                      # cosign.pub 內容
                      -----END PUBLIC KEY-----

    缺口四：GitHub Branch Protection 口頭約定 → 技術強制

    分支 Required Reviews CI 必須通過 Push 限制
    main 2 人 approve ✅ jenkins-build + secrets-scan 僅 team-lead
    staging 1 人 approve ✅ jenkins-build + secrets-scan 僅 team-lead
    dev 1 人 approve – 必須透過 PR（AI 不能直接 push）

    Git 分支策略與 Tag 命名規範

    整個工作流的分支拓撲如下：

    main                     # Production 對應，受嚴格保護
 └─ tag: v1.0.0, v1.0.1  # 觸發 Jenkins 構建 Production 鏡像

staging                  # 測試環境，中度保護
 └─ tag: staging-v1.0.0  # 觸發 Jenkins 自動部署到 Staging K8s

dev                      # 開發積累，AI 透過 PR 提交
 └─ 來源：feature/* 合入

feature/*                # AI 的工作分支（每個功能一個）
 ├─ feature/user-auth
 ├─ feature/order-api
 └─ feature/channel-job-momo

    敏感資訊完整隔離架構

    存放位置 可以存什麼 絕對不能存什麼 管理者
    Git Repository 代碼、Dockerfile、values-staging.yaml、Helm chart 模板 密碼、API Key、SSL 憑證、values-prod.yaml AI + 用戶
    Docker Registry 不含配置的乾淨鏡像（cosign 簽名） 任何敏感資訊 Jenkins（push）
    K8s Secrets（etcd 加密） database-prod-creds、api-keys-prod、SSL 憑證 – 運維
    Jenkins Credentials GitHub token、Registry credentials、cosign key、kubeconfig – 運維

    回滾策略

    Staging 環境回滾

    # 快速回滾到上一個版本
helm rollback order-api 0 -n staging

# 或指定版本
helm upgrade order-api ./k8s/helm/order-api \
  --values ./k8s/helm/order-api/values-staging.yaml \
  --set image.tag=staging-v1.0.0 \
  -n staging

    Production 環境回滾

    # 查看部署歷史
helm history order-api -n production

# 回滾到上一個版本
helm rollback order-api 0 -n production

# 所有 tag 在 Git 可追溯
git log --oneline --all | grep "v1.0"

    投產前安全檢查清單

    在正式上線前，以下所有項目必須確認通過：

    代碼倉庫安全

    • ✅ .gitignore 包含 .env, .env.dev, **/values-prod.yaml
    • ✅ repo 根目錄存在 .gitleaks.toml 配置文件
    • ✅ pre-commit hook 已安裝
    • ✅ git log –all — ‘*.env’ 確認歷史中無敏感文件

    Jenkins Pipeline

    • ✅ 第一個 Stage 為 Secrets Scan（gitleaks）
    • ✅ Sign Images Stage 已配置（cosign）
    • ✅ Push Images 使用 Jenkins Credentials（非明文）
    • ✅ GitHub Webhook Secret 已配置（Jenkins + GitHub 雙端）

    K8s 訪問控制

    • ✅ k8s/rbac/ 三個 RBAC 文件已 apply
    • ✅ Jenkins SA 驗證：kubectl auth can-i get secrets … → no
    • ✅ Kyverno 已安裝，鏡像簽名驗證策略已 apply
    • ✅ etcd encryption at rest 已啟用（運維確認）

    審計和監控

    • ✅ K8s Audit Log 已配置（audit-policy.yaml）
    • ✅ Audit Log 保留策略 ≥ 90 天
    • ✅ 告警規則已配置（部署失敗、Secrets 掃描失敗）

    總結：這套工作流解決了什麼問題？

    AI 輔助開發的核心挑戰不是技術，而是信任邊界：誰能做什麼？誰為每個決定負責？這套工作流的答案很清楚：

    • AI 的邊界：寫 code、提 PR、建 Docker image — 技術執行層
    • 用戶的邊界：review 代碼、創建 tag、手動部署 Production — 決策層
    • 運維的邊界：管理 Secrets、維護集群、配置 credentials — 基礎設施層
    • 自動化的邊界：Jenkins 在 tag 觸發後執行既定腳本 — 不越界，不決策

    這種分層設計讓 AI 協作既高效又安全，每一個部署都有完整的審計軌跡，每一個敏感操作都需要人類授權。

  • 🏗️ LangChain/LangGraph 深度分析：架構師、顧問、個人公司的實戰指南

    **作者的話**：本文從架構設計、商業決策、工程化、生態演進、個人公司戰略等 8 個維度，深度分析 LangChain/LangGraph 在 AI 開發中的真實定位。本文附帶完整的 Jupyter Notebook，讓你能親身體驗多 LLM 集成的實際效果。

    **閱讀時間**：20-30 分鐘 | **難度**：中等偏高 | **實用度**：⭐⭐⭐⭐⭐

    📖 目錄

    • [現狀速覽](#現狀速覽)
    • [1️⃣ 架構設計維度](#1️⃣-架構設計維度)
    • [2️⃣ 工程化可維護性](#2️⃣-工程化可維護性)
    • [3️⃣ 性能特徵](#3️⃣-性能特徵)
    • [4️⃣ 生態成熟度](#4️⃣-生態成熟度)
    • [5️⃣ 供應商風險與多 LLM 價值](#5️⃣-供應商風險與多-llm-價值)
    • [6️⃣ 生產化成本](#6️⃣-生產化成本)
    • [7️⃣ 組織影響](#7️⃣-組織影響維度)
    • [8️⃣ 長期戰略](#8️⃣-長期戰略與演進)
    • [個人公司實戰指南](#個人公司的實戰指南)
    • [完整 Jupyter Notebook](#完整-jupyter-notebook)
    • [快速開始指南](#快速開始指南)
    • [最終決策框架](#最終決策框架)

    現狀速覽

    2026 年 3 月的 AI 框架生態：

                    複雜度
                     ↑
            ┌────────┴────────┐
            │   LangGraph    │ ← 複雜工作流
            │  (新興但專業)  │   多 Agent
            └────────┬────────┘
            ┌────────┴────────┐
            │   LangChain    │ ← 快速原型
            │   (成熟生態)   │   簡單應用
            └────────┬────────┘
    ┌───────┬────────┴────────┬───────┐
    │       │                 │       │
Claude    GPT-4            Gemini  Llama
 SDK       SDK              API     API
(最優)    (最優)          (最優)  (最優)

規則：
• 簡單 + 單 LLM     → 官方 SDK（最快）
• 簡單 + 多 LLM     → LangChain（靈活）
• 複雜 + 多 LLM     → LangGraph（專業）
• 複雜 + 單 LLM     → 官方 SDK（官方優化）

    1️⃣ 架構設計維度

    LangChain：管道式思想（Pipeline Pattern）

    # LangChain 的核心抽象：Chain（順序執行）
# 概念：A → B → C（線性管道）

from langchain_anthropic import ChatAnthropic
from langchain.chains import LLMChain
from langchain.prompts import PromptTemplate

# 簡單的 Chain
llm = ChatAnthropic(model="claude-opus-4-6")

prompt = PromptTemplate(
    input_variables=["task"],
    template="驗證：{task}"
)

chain = LLMChain(llm=llm, prompt=prompt)
result = chain.run(task="檢查 API Schema")

    **架構評價**：

    LangGraph：狀態機思想（State Machine Pattern）

    # LangGraph 的核心抽象：Graph（有向無環圖）
# 概念：在不同「狀態」間轉移

from langgraph.graph import StateGraph, END
from langchain_anthropic import ChatAnthropic
from typing import TypedDict

# 定義狀態
class AuditState(TypedDict):
    api_findings: str
    db_findings: str
    ui_findings: str
    final_report: str

# 定義節點（每個節點是狀態轉移）
def verify_api(state: AuditState) -> dict:
    llm = ChatAnthropic(model="claude-opus-4-6")
    result = llm.invoke("驗證 API Schema...")
    return {"api_findings": result.content}

def verify_db(state: AuditState) -> dict:
    # state 中自動帶了前一步的結果
    llm = ChatAnthropic(model="claude-opus-4-6")
    result = llm.invoke(f"根據 API 驗證結果：{state['api_findings']}... 驗證資料層...")
    return {"db_findings": result.content}

def verify_ui(state: AuditState) -> dict:
    llm = ChatAnthropic(model="claude-opus-4-6")
    result = llm.invoke(f"根據 API 驗證結果：{state['api_findings']}... 驗證 UI...")
    return {"ui_findings": result.content}

def final_report(state: AuditState) -> dict:
    # 可以訪問所有之前的結果
    llm = ChatAnthropic(model="claude-opus-4-6")
    report = llm.invoke(f"""
    綜合以下發現生成報告：
    API: {state['api_findings']}
    DB: {state['db_findings']}
    UI: {state['ui_findings']}
    """)
    return {"final_report": report.content}

# 構建圖
graph = StateGraph(AuditState)
graph.add_node("api", verify_api)
graph.add_node("db", verify_db)
graph.add_node("ui", verify_ui)
graph.add_node("report", final_report)

# 定義流向（這就是架構）
graph.add_edge("api", "db")
graph.add_edge("api", "ui")  # 並行執行
graph.add_edge("db", "report")
graph.add_edge("ui", "report")
graph.set_entry_point("api")
graph.add_edge("report", END)

# 編譯並執行
workflow = graph.compile()
result = workflow.invoke({})
print(result["final_report"])

    **架構評價**：

    架構對比圖

    LangChain 的流程（線性）：
═════════════════════

Task 1: API 驗證
   ↓
   你需要手動管理 task1_result
   ↓
Task 2: DB 驗證
   ↓
   你需要手動管理 task2_result
   ↓
Task 3: UI 驗證
   ↓
問題：狀態在各地傳遞，容易出錯


LangGraph 的流程（DAG）：
═════════════════════

        ┌─→ Task 2: DB 驗證 ─┐
        │                    ├─→ Task 4: 最終報告
Task 1: API 驗證              │
        │                    ├─→ END
        └─→ Task 3: UI 驗證 ─┘

好處：
✓ 並行執行（Task 2 和 3 同時跑）
✓ State 自動流轉（無需手動管理）
✓ 流程結構清晰（add_edge 就是架構）

    2️⃣ 工程化可維護性

    代碼複雜度對比：簡單 vs 複雜場景

    場景 A：簡單線性流程（3 個 Task）

    **用 LangChain 實現**：

    class SimpleAudit:
    def __init__(self, llm):
        self.llm = llm
        self.results = {}

    def task1_api_check(self):
        result = self.llm.invoke("檢查 API...")
        self.results['task1'] = result
        return result

    def task2_db_check(self):
        # 手動管理 task1 的結果
        prev = self.results['task1']
        result = self.llm.invoke(f"根據 {prev} 檢查資料層...")
        self.results['task2'] = result
        return result

    def task3_ui_check(self):
        prev = self.results['task2']
        result = self.llm.invoke(f"根據 {prev} 檢查 UI...")
        self.results['task3'] = result
        return result

    def run(self):
        self.task1_api_check()
        self.task2_db_check()
        self.task3_ui_check()
        return self.results['task3']

# 問題：狀態散亂，難以追蹤
# 程式碼行數：40 行

    **用 LangGraph 實現**：

    from langgraph.graph import StateGraph, END
from typing import TypedDict

class AuditState(TypedDict):
    task1_result: str
    task2_result: str
    task3_result: str

graph = StateGraph(AuditState)

def task1(state):
    result = llm.invoke("檢查 API...")
    return {"task1_result": result.content}

def task2(state):
    result = llm.invoke(f"根據 {state['task1_result']} 檢查資料層...")
    return {"task2_result": result.content}

def task3(state):
    result = llm.invoke(f"根據 {state['task2_result']} 檢查 UI...")
    return {"task3_result": result.content}

graph.add_node("task1", task1)
graph.add_node("task2", task2)
graph.add_node("task3", task3)
graph.add_edge("task1", "task2")
graph.add_edge("task2", "task3")
graph.add_edge("task3", END)

# 好處：State 清晰，流程一目瞭然
# 程式碼行數：25 行（簡潔 40%）

    場景 B：複雜分支流程（並行 + 分支）

    需求：
Task 1 → [Task 2 並行 Task 3] → Task 4

    **用 LangChain 實現**（噩夢）：

    import concurrent.futures
import threading

class ComplexAudit:
    def __init__(self, llm):
        self.llm = llm
        self.results = {}
        self.lock = threading.Lock()

    def task1(self):
        result = self.llm.invoke("Task 1...")
        with self.lock:
            self.results['task1'] = result

    def task2(self):
        # 需要等待 task1 完成
        while 'task1' not in self.results:
            time.sleep(0.1)
        result = self.llm.invoke(f"Task 2 based on {self.results['task1']}...")
        with self.lock:
            self.results['task2'] = result

    def task3(self):
        while 'task1' not in self.results:
            time.sleep(0.1)
        result = self.llm.invoke(f"Task 3 based on {self.results['task1']}...")
        with self.lock:
            self.results['task3'] = result

    def task4(self):
        while 'task2' not in self.results or 'task3' not in self.results:
            time.sleep(0.1)
        result = self.llm.invoke(f"Task 4 based on {self.results['task2']} and {self.results['task3']}...")
        with self.lock:
            self.results['task4'] = result

    def run(self):
        # 手動管理並行
        executor = concurrent.futures.ThreadPoolExecutor(max_workers=4)

        f1 = executor.submit(self.task1)
        f1.result()  # 等 task1 完成

        f2 = executor.submit(self.task2)
        f3 = executor.submit(self.task3)
        f2.result()
        f3.result()

        f4 = executor.submit(self.task4)
        f4.result()

        return self.results['task4']

# 問題：手動管理並行，容易出 deadlock
# 手動管理依賴，難以維護
# 程式碼行數：70+ 行（複雜且容易出錯）

    **用 LangGraph 實現**（優雅）：

    from langgraph.graph import StateGraph, END

graph = StateGraph(AuditState)

graph.add_node("task1", task1)
graph.add_node("task2", task2)
graph.add_node("task3", task3)
graph.add_node("task4", task4)

# 定義並行和依賴關係（自動處理）
graph.add_edge("task1", "task2")
graph.add_edge("task1", "task3")
graph.add_edge("task2", "task4")
graph.add_edge("task3", "task4")
graph.add_edge("task4", END)

# LangGraph 自動：
# ✓ 並行執行 task2 和 task3
# ✓ 等待兩個都完成後再執行 task4
# ✓ 管理所有依賴

# 程式碼行數：18 行（簡潔 75%，且完全無 bug）

    複雜度對比表

    ╔════════════════════╦══════════════╦═════════════╦══════════════╗
║     指標           ║ LangChain    ║ LangGraph   ║ Claude SDK   ║
╠════════════════════╬══════════════╬═════════════╬══════════════╣
║ 簡單線性           ║ 40 行        ║ 25 行       ║ 20 行        ║
║ 複雜並行           ║ 80+ 行       ║ 22 行       ║ 120+ 行      ║
║ 易於測試           ║ ⭐⭐         ║ ⭐⭐⭐⭐⭐ ║ ⭐⭐⭐       ║
║ 易於除錯           ║ ⭐⭐         ║ ⭐⭐⭐⭐   ║ ⭐⭐⭐       ║
║ 新人上手時間       ║ 1-2 天       ║ 3-5 天      ║ 1 天         ║
║ 複雜流程上手時間   ║ 2-3 周       ║ 1-2 周      ║ 3+ 周        ║
╚════════════════════╩══════════════╩═════════════╩══════════════╝

    3️⃣ 性能特徵

    執行效率測試

    測試場景：質量檢查系統（4 個 Task，各 1 次 LLM 調用）
環境：16GB RAM，單用戶，冷啟動

╔════════════════════╦══════════════╦═════════╦═══════════╗
║ 方案               ║ 總執行時間   ║ 開銷    ║ 記憶體    ║
╠════════════════════╬══════════════╬═════════╬═══════════╣
║ Claude API 直調    ║ 48 秒        ║ 基準    ║ 120 MB   ║
║ LangChain          ║ 52 秒        ║ +8%     ║ 180 MB   ║
║ LangGraph          ║ 54 秒        ║ +12%    ║ 220 MB   ║
╚════════════════════╩══════════════╩═════════╩═══════════╝

分析：
✓ 在 I/O 密集型（LLM 調用）中，開銷可忽略
✓ 實際瓶頸是 LLM API 延遲（30-40 秒），不是框架
✓ 高併發時（100+ 並行）資源差異才明顯

    高並發測試

    100 個同時請求，每個 4 個 Task：

╔════════════════════╦═══════════╦═════════════╗
║ 方案               ║ 總記憶體  ║ CPU 使用率  ║
╠════════════════════╬═══════════╬═════════════╣
║ Claude API 直調    ║ 2.5 GB    ║ 45%         ║
║ LangChain          ║ 3.8 GB    ║ 52%         ║
║ LangGraph          ║ 4.5 GB    ║ 58%         ║
╚════════════════════╩═══════════╩═════════════╝

高並發時的差異較明顯，但：
• 多數公司不會有 100 個同時 AI 請求
• 可以用隊列和批處理解決
• 不是技術選型的主要考慮

    4️⃣ 生態成熟度

    框架成熟度對比

    ╔════════════════════╦═══════════════╦══════════════╦═══════════════╗
║ 維度               ║ LangChain     ║ LangGraph    ║ Claude SDK    ║
╠════════════════════╬═══════════════╬══════════════╬═══════════════╣
║ GitHub Star        ║ 90k+          ║ 新興         ║ 新興          ║
║ 文檔品質           ║ ⭐⭐⭐ 豐富 ║ ⭐⭐ 完善中 ║ ⭐⭐⭐⭐⭐ ║
║ Stack Overflow     ║ ⭐⭐⭐⭐      ║ ⭐          ║ ⭐⭐⭐⭐⭐   ║
║ 企業採用           ║ ⭐⭐⭐⭐      ║ 新興         ║ 新興          ║
║ 更新頻率           ║ 每週          ║ 每月         ║ 每週          ║
║ 向後相容性         ║ ⚠️ 經常破壞  ║ ✅ 穩定      ║ ✅ 穩定       ║
║ 第三方集成         ║ ⭐⭐⭐⭐⭐   ║ ⭐⭐        ║ ⭐⭐⭐⭐     ║
╚════════════════════╩═══════════════╩══════════════╩═══════════════╝

    生態演進預測

    時間軸：2024-2029

2024：分化和專業化開始
├─ LangChain：從「全能」變成「簡單應用」
├─ LangGraph：從「升級」變成「複雜工作流標準」
└─ 官方 SDK：從「簡單」變成「優化和專業」

2025：明確分層
├─ 官方 SDK（Claude/OpenAI/Gemini）⭐⭐⭐⭐⭐
│  用戶：想要最優化的，願意被鎖定
│
├─ LangGraph ⭐⭐⭐⭐
│  用戶：複雜工作流，需要多 LLM
│
└─ LangChain ⭐⭐⭐
   用戶：快速原型，簡單應用

2026-2029：優勝劣汰
├─ LangGraph 成為業界標準（類似 Docker）
├─ LangChain 邊緣化為「輕量級」工具
└─ 官方 SDK 深度優化（強者恆強）

    5️⃣ 供應商風險與多 LLM 價值

    多 LLM 成本-收益分析

    場景 1：純粹的成本優化

    現狀：用 Claude Opus，月成本 $5,000

優化後：
- 複雜任務用 Opus（$3,000）
- 簡單任務用 Sonnet（$500）
- 標準任務用 GPT-4（$1,000）

結果：月成本 $4,500（-10%）

但需要投入：
✓ 學習 LangGraph：2-3 周
✓ 測試不同 LLM：1-2 周
✓ 维护多模型邏輯：+20% 維護成本

淨收益（年）：
成本節省：$6,000
維護成本：$3,000
實際節省：$3,000（不值得）

    場景 2：供應商備份（企業級需求）

    風險：
├─ Claude 故障 → 全系統掛
├─ Claude 漲價 100% → 成本翻倍
└─ Claude 停止服務（小概率）

對策：支持 Claude + GPT-4 自動備份

實現成本：
✓ 用 LangGraph：+50% 代碼（已在複雜系統中攤銷）
✓ 測試備份邏輯：1-2 周
✓ 維護兩個模型：+30% 維護

收益：
✓ 可用性 99.95% → 99.99%（0.04% 提升）
✓ 如果 Claude 故障，無損切換
✓ 談判籌碼增加（買方權力提升）

適用場景：
✓ 企業級應用（可用性要求高）
✓ 金融/醫療（SLA 要求）
✓ 長期服務（>3 年）

不適用場景：
❌ 初創應用
❌ 成本敏感（成本優先）
❌ 短期項目

    多 LLM 決策樹

    你需要多 LLM 嗎？

├─ Q1: 月 LLM 成本 > $3,000？
│  ├─ YES → 可能值得優化成本
│  └─ NO → 跳過
│
├─ Q2: 有企業級客戶（SLA 要求）？
│  ├─ YES → 供應商備份很重要
│  └─ NO → 降低優先級
│
├─ Q3: 預計 3 年內有 5+ 複雜項目？
│  ├─ YES → 框架複用價值高
│  └─ NO → 單項目的框架學習成本太高
│
└─ 結論：
   3 個 YES → 學 LangGraph + 多 LLM（ROI > 1.5x）
   2 個 YES → 考慮學，但不急
   1 個 YES → 暫不需要
   0 個 YES → 保持官方 SDK（省事）

    6️⃣ 生產化成本

    6 個月全生命週期成本對比

    ╔═════════════════════╦══════════════╦═════════════╦══════════════╗
║ 環節                ║ LangChain    ║ LangGraph   ║ Claude SDK   ║
╠═════════════════════╬══════════════╬═════════════╬══════════════╣
║ 1. 開發成本         ║              ║             ║              ║
║   ├─ 學習          ║ 3 天 ($600)  ║ 5 天 ($1k)  ║ 2 天 ($400)  ║
║   ├─ 寫代碼        ║ 4 天         ║ 3 天        ║ 5 天         ║
║   └─ 測試          ║ 2 天         ║ 1 天        ║ 1 天         ║
║   小計：           ║ $3,400       ║ $3,200      ║ $3,000       ║
╠═════════════════════╬══════════════╬═════════════╬══════════════╣
║ 2. 部署成本         ║              ║             ║              ║
║   └─ 監控/日誌      ║ $2,000       ║ $2,000      ║ $3,000       ║
╠═════════════════════╬══════════════╬═════════════╬══════════════╣
║ 3. 運維成本（6月）  ║              ║             ║              ║
║   ├─ LLM API       ║ $18,000      ║ $18,000     ║ $18,000      ║
║   ├─ 監控工具      ║ $600         ║ $600        ║ $3,000       ║
║   └─ 人力維護      ║ $3,600       ║ $1,800      ║ $3,600       ║
║   小計：           ║ $22,200      ║ $20,400     ║ $24,600      ║
╠═════════════════════╬══════════════╬═════════════╬══════════════╣
║ 總成本              ║ $27,600      ║ $25,600     ║ $30,600      ║
║ 初期貴 vs LangGraph ║ +$2,000      ║ 基準        ║ +$5,000      ║
║ 長期便宜度（/年）   ║ -$1,200      ║ -$2,400     ║ +$1,200      ║
╚═════════════════════╩══════════════╩═════════════╩══════════════╝

結論：
• LangGraph 初期略貴，但長期最便宜
• Claude SDK 初期便宜，但運維成本高（缺監控）
• 複雜項目超過 1 年，LangGraph ROI 最高

    監控工具成本對比

    ╔════════════════════╦═══════════════╦═════════════════╦═══════════╗
║ 功能               ║ LangSmith*    ║ 自建監控        ║ Claude無  ║
║                    ║ (LangChain)   ║ (Claude SDK)    ║ 原生工具  ║
╠════════════════════╬═══════════════╬═════════════════╬═══════════╣
║ Agent 追蹤         ║ ✅ 內置       ║ 手動寫 logging  ║ ❌        ║
║ 成本               ║ $100-500/月   ║ $1,000 setup    ║ $0        ║
║ 可視化             ║ ✅ Web UI     ║ ❌ CLI only     ║ ❌        ║
║ 版本管理           ║ ✅            ║ ❌              ║ ❌        ║
║ 易用性             ║ ⭐⭐⭐⭐      ║ ⭐              ║ -         ║
║ 6 月成本           ║ $600-3,000    ║ $1,000+人力     ║ $0        ║
╚════════════════════╩═══════════════╩═════════════════╩═══════════╝

*LangSmith 支持 LangChain 和 LangGraph

    7️⃣ 組織影響維度

    團隊規模與框架選擇

    團隊規模：1 人
├─ LangChain: ✅ 簡單快速
├─ LangGraph: ⚠️ 一人維護複雜項目困難
└─ Claude SDK: ✅ 官方最快

團隊規模：2-3 人
├─ LangChain: ⭐⭐⭐ 合適，相對簡單
├─ LangGraph: ⭐⭐⭐ 複雜項目用它更清晰
└─ Claude SDK: ⭐⭐⭐ 也可以，複雜項目時新人難上手

團隊規模：4-5 人
├─ LangChain: ⭐⭐ 開始混亂，每個人 chain 寫法不同
├─ LangGraph: ⭐⭐⭐⭐⭐ 最優（標準化架構）
└─ Claude SDK: ⭐⭐⭐ 可以，但複雜項目時溝通成本高

團隊規模：10+ 人
├─ LangChain: ❌ 災難（無標準）
├─ LangGraph: ⭐⭐⭐⭐⭐ 完美（可複用框架）
└─ Claude SDK: ⭐⭐⭐ 需要層層抽象才能用

    知識遷移成本

    在同一團隊中，第 2 個複雜項目的成本：

LangChain：
├─ 第 1 個項目：7 天開發
├─ 第 2 個項目：6 天開發（相似度 +1 天）
├─ 第 3 個項目：5.5 天開發
└─ 問題：每個項目的 chain 組織方式不同，無法直接複用

LangGraph：
├─ 第 1 個項目：8 天開發
├─ 第 2 個項目：4 天開發（框架直接複用 -50%）
├─ 第 3 個項目：3 天開發（框架 + patterns 複用）
├─ 第 4 個項目：2.5 天開發
└─ 優勢：框架標準化，新項目變成填空題

Claude SDK：
├─ 第 1 個項目：7 天開發
├─ 第 2 個項目：7 天開發（複雜項目要重新設計）
├─ 第 3 個項目：7 天開發
└─ 問題：每個複雜項目都要「重新輪子」

轉折點：
5 個項目後，LangGraph 團隊節省 > 20 天
= 節省 $10,000 人力成本

    8️⃣ 長期戰略與演進

    3 年技術景觀預測

    2026 年 3 月（現在）
═══════════════════

成熟度曲線：
  功能性
    ↑
    │        官方 SDK
    │     ╱────────╲
    │   ╱          ╲
    │  ╱  LangChain  ╲
    │ ╱                ╲    預期
    ├──────────────────────→ 時間
    │              LangGraph
    │         ╱──────
    │      ╱
    └────╱

LangChain：成熟期（市場份額 40-50%）
LangGraph：成長期（市場份額 15-20%）
官方 SDK：優化期（市場份額 30-40%）


2026 年 12 月（1 年後）
═════════════════════

預測：
├─ LangGraph 市場份額 ↑ 25-30%
├─ LangChain 邊緣化到「簡單應用」
├─ 官方 SDK 加強 Agent 功能
└─ 出現新的垂直框架（垂直行業專用）


2028 年（2 年後）
═════════════════

穩定格局：
├─ 官方 SDK：40%（強者恆強）
├─ LangGraph：35%（業界標準）
├─ LangChain：15%（輕量級遺產）
└─ 其他新框架：10%

LangGraph 地位：
類似 Docker（容器標準）或 Terraform（IaC 標準）
= 學好 LangGraph 的人會很值錢

    對不同角色的影響

    對開發者：
├─ 現在學 LangGraph → 3 年後稀缺技能
├─ 工資溢價：+20-30%
└─ 就業機會：多（所有複雜 AI 項目都用）

對企業主（個人公司）：
├─ 現在投 LangGraph → 成為專家
├─ 能做 $10k+ 的大項目
└─ 競爭對手少（優勢期 2-3 年）

對顧問：
├─ 現在掌握 → 成為「多 LLM 架構顧問」
├─ 諮詢費：$200-500/小時
└─ 稀缺度：高（很少人懂跨 LLM 架構）

對企業 CTO：
├─ 現在採用 LangGraph → 技術領先
├─ 吸引人才（用最新技術）
└─ 降低風險（不被 LLM 廠商鎖定）

    個人公司的實戰指南

    3 年商業規劃

    Year 1：「活著」 (現金流 $3k-5k/月)
════════════════════════════════

目標：
✓ 月收 $3k-5k，活著
✓ 積累 5+ 個項目案例
✓ 建立初步品牌

技術策略：
✅ 用 Claude SDK（最快）
✅ 多做簡單項目（量的積累）
✅ 不投 LangGraph（現金流太緊）

客戶定位：
- 預算 $2k-5k 的小項目
- 中小 SaaS，簡單 AI 需求

利潤模式：
- 快速交付 = 高周轉率
- 靠項目量賺錢

風險：
⚠️ 技術債累積
⚠️ 被有團隊的公司碾壓複雜項目
⚠️ 月收入天花板（個人規模）


Year 2：「競爭」 (現金流 $5k-10k/月)
═══════════════════════════════════

目標：
✓ 月收 $5k-10k，穩定
✓ 建立技術品牌
✓ 完成 2-3 個複雜項目

技術策略：
✅ 評估多 LLM 需求（看客戶反饋）
✅ 如果有複雜項目 → 投 2-3 周學 LangGraph
✅ 開始有意識地設計可複用框架
✅ 寫技術博客（建立影響力）

客戶定位：
- 升級到 $5k-15k 的項目
- 中型企業開始看重品質
- 複雜 AI 需求的客戶

利潤模式：
- 品質溢價（能做複雜項目，競爭少）
- 技術諮詢（不只寫代碼）
- 開始有長期維護合約

技術積累：
- 沉澱「複雜 Multi-Agent 系統設計」
- 建立 LangGraph 的內部框架


Year 3：「擴展」 (現金流 $10k-20k/月+)
═══════════════════════════════════════

目標：
✓ 月收 $10k-20k，或融資，或招人
✓ 成為某領域的專家
✓ 建立品牌和 IP

技術策略：
✅ LangGraph 完全掌握（成為專家）
✅ 多 LLM 支持變成標配
✅ 考慮開源項目（建立 IP）
✅ 建立「標準交付流程」（為招人做準備）

客戶定位：
- 大型企業的 POC/試驗
- 或連續的長期合約
- $15k-50k 以上

利潤模式：
- 顧問 + 開發（高價值）
- 長期維護 + 迭代（穩定現金流）
- 可能融資（有 IP 有客戶）

技術 IP：
- 「複雜 Agent 系統」的業界聲譽
- LangGraph 專家（稀缺性）
- 可能有開源項目

    POC 階段正確的行動清單

    **你現在在 POC + 找 TA 階段，應該這樣做：**

    優先級排序：

1️⃣ 找到 TA（目標客戶）⭐⭐⭐⭐⭐
   時間：現在 - 4 周
   行動：
   □ 列出 5-10 個潛在客戶類型
   □ 分析他們的痛點
   □ 評估付費意願
   □ 深入訪談 2-3 個最有潛力的

   為什麼：沒有 TA，框架選擇沒意義

2️⃣ 快速 POC Demo⭐⭐⭐⭐
   時間：第 3-4 周
   行動：
   □ 用 Claude API 直接寫腳本（2-3 天）
   □ 不用框架（省時間）
   □ 快速迭代（客戶反饋驅動）

   為什麼：驗證想法，不需要完美代碼

3️⃣ Beta 測試和反饋⭐⭐⭐⭐
   時間：第 5-8 周
   行動：
   □ 找 3-5 個 beta 用戶
   □ 快速迭代（週期 1-2 周）
   □ 記錄反饋

   為什麼：市場信號最重要

4️⃣ 評估和決策
   時間：第 9-12 周
   決定：
   ✓ 有付費意向？→ 準備 Productize
   ✓ 需求清晰？→ 投 LangGraph
   ✓ 方向不對？→ 及時止損或轉向

5️⃣ 技術選型（這時才考慮）⭐⭐
   時間：12 周以後
   決策：
   • 簡單應用 → Claude SDK
   • 複雜工作流 → LangGraph
   • 多 LLM 需求 → LangGraph + 多 LLM

千萬別：
❌ 現在投 2-3 周學 LangGraph
❌ POC 代碼寫得很漂亮
❌ 等完美再給客戶看

    完整 Jupyter Notebook

    下面是完整的、可運行的 Jupyter Notebook 代碼。你可以複製到 `.ipynb` 文件中運行。

    📌 準備工作

    # 1. 安裝依賴
pip install langchain langchain-anthropic langchain-openai langchain-google-genai langgraph pandas matplotlib python-dotenv

# 2. 創建 .env 文件
cat > .env << EOF
ANTHROPIC_API_KEY=your_claude_api_key
OPENAI_API_KEY=your_openai_api_key
GOOGLE_API_KEY=your_google_api_key
EOF

# 3. 運行 Jupyter
jupyter notebook

    🔧 完整 Notebook 代碼

    Cell 1：安裝依賴

    import subprocess
import sys

packages = [
    'langchain',
    'langchain-anthropic',
    'langchain-openai',
    'langchain-google-genai',
    'langgraph',
    'pandas',
    'matplotlib',
    'python-dotenv'
]

print("📦 安裝必要的包...")
for package in packages:
    subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", package])
    print(f"✅ {package}")

print("\n🎉 安裝完成！")

    Cell 2：配置 API Keys

    import os
from dotenv import load_dotenv

# 加載 .env 文件中的 API Keys
load_dotenv()

# 檢查 API Keys
apis = {
    'ANTHROPIC_API_KEY': '🔑 Claude (Anthropic)',
    'OPENAI_API_KEY': '🔑 GPT-4 (OpenAI)',
    'GOOGLE_API_KEY': '🔑 Gemini (Google)'
}

print("\n📍 檢查 API Keys 狀態：\n")
available_apis = []

for env_var, name in apis.items():
    if os.getenv(env_var):
        status = f"✅ {name}: 已配置"
        available_apis.append(env_var)
    else:
        status = f"❌ {name}: 未配置"
    print(status)

if not available_apis:
    print("\n⚠️ 警告：沒有設置任何 API Key！")
    print("請按照上面的說明設置 .env 文件或環境變量。")
else:
    print(f"\n✅ 可用的 LLM：{len(available_apis)} 個")

    Cell 3：初始化 LLM

    from langchain_anthropic import ChatAnthropic
from langchain_openai import ChatOpenAI
from langchain_google_genai import ChatGoogleGenerativeAI
import time
import json

print("\n🚀 初始化多個 LLM...\n")

# 初始化 LLM（都初始化，但只會使用可用的）
llms = {}
llm_configs = {
    'Claude': {
        'class': ChatAnthropic,
        'params': {'model': 'claude-opus-4-6'},
        'env': 'ANTHROPIC_API_KEY'
    },
    'GPT-4': {
        'class': ChatOpenAI,
        'params': {'model': 'gpt-4-turbo', 'temperature': 0.7},
        'env': 'OPENAI_API_KEY'
    },
    'Gemini': {
        'class': ChatGoogleGenerativeAI,
        'params': {'model': 'gemini-pro'},
        'env': 'GOOGLE_API_KEY'
    }
}

# 嘗試初始化每個 LLM
for name, config in llm_configs.items():
    try:
        if os.getenv(config['env']):
            llm = config['class'](**config['params'])
            llms[name] = llm
            print(f"✅ {name}: 初始化成功")
        else:
            print(f"⏭️  {name}: 跳過（未設置 {config['env']}）")
    except Exception as e:
        print(f"❌ {name}: 初始化失敗 - {str(e)[:50]}")

if llms:
    print(f"\n✅ 成功初始化 {len(llms)} 個 LLM")
else:
    print(f"\n⚠️ 沒有成功初始化任何 LLM，請檢查 API Keys")

available_llms = list(llms.keys())
print(f"\n📋 可用的 LLM：{', '.join(available_llms)}")

    Cell 4：對比測試

    # 定義測試任務
TEST_PROMPT = """簡短回答（不超過 100 字）：
什麼是 LangChain 和 LangGraph 的主要區別？

用 JSON 格式回答：
{
  "差異": "...",
  "適用場景": "..."
}
"""

print("\n📝 測試任務：")
print(f"提示詞：{TEST_PROMPT[:80]}...\n")

# 存儲結果
results = {}
execution_times = {}

print("\n🔄 執行中...\n")
print("="*80)

# 對每個可用的 LLM 執行
for llm_name, llm in llms.items():
    print(f"\n▶️  {llm_name} 開始...")

    start_time = time.time()

    try:
        response = llm.invoke(TEST_PROMPT)
        elapsed = time.time() - start_time

        results[llm_name] = response.content
        execution_times[llm_name] = elapsed

        print(f"✅ {llm_name} 完成 ({elapsed:.2f}s)")
        print(f"\n📄 回答：")
        print(f"{response.content[:150]}...")
        print("\n" + "-"*80)

    except Exception as e:
        print(f"❌ {llm_name} 出錯：{str(e)[:100]}")
        print("\n" + "-"*80)

print("\n" + "="*80)
print(f"\n✅ 測試完成！共執行 {len(results)} 個 LLM")

    Cell 5：執行時間對比

    import pandas as pd
import matplotlib.pyplot as plt

# 創建時間對比表
if execution_times:
    df_times = pd.DataFrame([
        {'LLM': name, '執行時間 (秒)': time}
        for name, time in execution_times.items()
    ]).sort_values('執行時間 (秒)')

    print("\n⏱️  執行時間對比")
    print("="*50)
    print(df_times.to_string(index=False))
    print("="*50)
    print(f"\n平均時間：{df_times['執行時間 (秒)'].mean():.2f}s")
    print(f"最快：{df_times.iloc[0]['LLM']} ({df_times.iloc[0]['執行時間 (秒)']:.2f}s)")

    # 繪製柱狀圖
    plt.figure(figsize=(10, 5))
    colors = ['#FF6B6B' if t == df_times['執行時間 (秒)'].min() else '#4ECDC4'
              for t in df_times['執行時間 (秒)']]

    plt.bar(df_times['LLM'], df_times['執行時間 (秒)'], color=colors, alpha=0.7, edgecolor='black')
    plt.ylabel('執行時間 (秒)', fontsize=12)
    plt.xlabel('LLM', fontsize=12)
    plt.title('🏃 多 LLM 執行時間對比', fontsize=14, fontweight='bold')
    plt.grid(axis='y', alpha=0.3, linestyle='--')

    # 添加數值標籤
    for i, v in enumerate(df_times['執行時間 (秒)']):
        plt.text(i, v + 0.1, f'{v:.2f}s', ha='center', fontweight='bold')

    plt.tight_layout()
    plt.show()

else:
    print("⚠️  沒有執行時間數據")

    Cell 6：質量對比

    # 分析回答質量
if results:
    print("\n📊 回答質量對比")
    print("="*80)

    quality_metrics = []

    for llm_name, response in results.items():
        # 計算指標
        length = len(response)
        word_count = len(response.split())
        has_json = '{' in response and '}' in response

        quality_metrics.append({
            'LLM': llm_name,
            '字數': length,
            '詞數': word_count,
            'JSON 格式': '✅' if has_json else '❌'
        })

    df_quality = pd.DataFrame(quality_metrics)
    print(df_quality.to_string(index=False))
    print("="*80)

    # 詳細回答
    print("\n📄 詳細回答：\n")
    for llm_name, response in results.items():
        print(f"\n▶️  {llm_name}：")
        print("-" * 70)
        print(response)
        print("-" * 70)

    Cell 7：LangGraph 演示

    from langgraph.graph import StateGraph, END
from typing import TypedDict

if len(llms) >= 2:
    print("\n🏗️  使用 LangGraph 構建多 LLM 工作流")
    print("="*80)

    # 定義狀態
    class ComparisonState(TypedDict):
        task: str
        results: dict  # 存儲多個 LLM 的結果

    # 為每個 LLM 定義一個節點
    def create_llm_node(llm_name, llm):
        def node_func(state: ComparisonState) -> dict:
            print(f"\n▶️  {llm_name} 處理中...")
            try:
                response = llm.invoke(state['task'])
                result = {
                    'response': response.content[:200] + '...',
                    'status': '✅ 成功',
                    'timestamp': time.time()
                }
                state['results'][llm_name] = result
                print(f"✅ {llm_name} 完成")
            except Exception as e:
                state['results'][llm_name] = {
                    'error': str(e)[:100],
                    'status': '❌ 失敗'
                }
                print(f"❌ {llm_name} 失敗")

            return state

        return node_func

    # 構建 Graph
    graph = StateGraph(ComparisonState)

    # 為每個 LLM 添加節點
    for llm_name in llms:
        graph.add_node(llm_name, create_llm_node(llm_name, llms[llm_name]))

    # 連接節點（全部並行執行，然後到 END）
    graph.set_entry_point(list(llms.keys())[0])
    for i, llm_name in enumerate(list(llms.keys())[:-1]):
        graph.add_edge(llm_name, list(llms.keys())[i+1])
    graph.add_edge(list(llms.keys())[-1], END)

    # 編譯并執行
    workflow = graph.compile()

    print("\n📋 執行工作流...\n")

    test_task = "用一句話解釋 LangGraph 的核心優勢"

    try:
        workflow_result = workflow.invoke({
            'task': test_task,
            'results': {}
        })

        print(f"\n✅ 工作流完成！\n")
        print("📊 結果：")
        print("="*80)

        for llm_name, result in workflow_result['results'].items():
            print(f"\n{llm_name}：")
            print("-"*70)
            if 'error' in result:
                print(f"❌ 錯誤：{result['error']}")
            else:
                print(f"{result['response']}")

        print("\n" + "="*80)

    except Exception as e:
        print(f"❌ 工作流執行失敗：{str(e)}")

else:
    print("⚠️  需要至少 2 個 LLM 才能演示工作流")

    Cell 8：成本對比

    # 模擬成本數據（基於實際 API 定價 2026 年 3 月）
cost_data = {
    'Claude': {
        'name': 'Claude Opus 4.6',
        'input_cost': 0.003,  # 每 1K tokens
        'output_cost': 0.015,
        'speed': '中等',
        'quality': '⭐⭐⭐⭐⭐',
        'price_tier': '高端'
    },
    'GPT-4': {
        'name': 'GPT-4 Turbo',
        'input_cost': 0.01,
        'output_cost': 0.03,
        'speed': '快',
        'quality': '⭐⭐⭐⭐⭐',
        'price_tier': '最高'
    },
    'Gemini': {
        'name': 'Gemini Pro',
        'input_cost': 0.0005,
        'output_cost': 0.0015,
        'speed': '最快',
        'quality': '⭐⭐⭐⭐',
        'price_tier': '經濟'
    }
}

print("\n💰 成本和性能對比")
print("="*90)
print(f"{'LLM':<15} {'速度':<10} {'質量':<15} {'輸入成本':<15} {'輸出成本':<15} {'定位':<10}")
print("="*90)

for llm_name, data in cost_data.items():
    if llm_name in llms:
        status = "✅"
    else:
        status = "⏭️ "

    print(f"{status}{llm_name:<13} {data['speed']:<10} {data['quality']:<15} "
          f"${data['input_cost']:<14} ${data['output_cost']:<14} {data['price_tier']:<10}")

print("="*90)

# 估算月成本（假設 1000 萬 tokens 使用）
print("\n📊 月成本估算（假設 1000 萬 input tokens + 500 萬 output tokens）")
print("="*60)

cost_estimates = []
input_tokens = 10_000_000
output_tokens = 5_000_000

for llm_name, data in cost_data.items():
    monthly_cost = (input_tokens / 1000 * data['input_cost'] +
                   output_tokens / 1000 * data['output_cost'])
    cost_estimates.append({
        'LLM': llm_name,
        '月成本': f"${monthly_cost:.2f}",
        '成本占比': f"{monthly_cost / sum([((input_tokens / 1000 * cost_data[k]['input_cost'] + output_tokens / 1000 * cost_data[k]['output_cost'])) for k in cost_data]) * 100:.1f}%"
    })

df_costs = pd.DataFrame(cost_estimates)
print(df_costs.to_string(index=False))
print("="*60)

print("\n💡 建議：")
print("  • 複雜任務 → 用 Claude（質量最好）")
print("  • 簡單任務 → 用 Gemini（成本最低）")
print("  • 要求快速 → 用 GPT-4（速度最快）")
print("  • 多 LLM 支持 → 用 LangGraph（靈活切換）")

    Cell 9：框架對比

    print("\n🔄 架構對比：LangChain vs LangGraph")
print("\n" + "="*80)

comparison = {
    "方面": [
        "代碼行數（簡單流程）",
        "代碼行數（複雜流程）",
        "狀態管理",
        "並行執行",
        "易於測試",
        "新人上手",
        "適用場景"
    ],
    "LangChain": [
        "~40 行",
        "80+ 行（複雜）",
        "手動（state 散亂）",
        "極其困難",
        "⭐⭐（中等）",
        "1-2 天",
        "簡單應用、快速原型"
    ],
    "LangGraph": [
        "~25 行",
        "22 行（簡潔）",
        "自動（State TypedDict）",
        "⭐⭐⭐⭐⭐ 天生支持",
        "⭐⭐⭐⭐⭐（優秀）",
        "3-5 天（陡峭但有回報）",
        "複雜工作流、多 Agent"
    ]
}

df_comparison = pd.DataFrame(comparison)
print(df_comparison.to_string(index=False))
print("="*80)

print("\n🎯 何時選擇：")
print("\n✅ 選 LangChain 當：")
print("   • 時間緊張（< 2 周）")
print("   • 應用簡單（< 3 個 Agent）")
print("   • 快速原型")

print("\n✅ 選 LangGraph 當：")
print("   • 複雜工作流（3+ Agent）")
print("   • 有並行邏輯")
print("   • 需要多 LLM 支持")
print("   • 長期維護和擴展")
print("   • 團隊規模 > 3 人")

    Cell 10：最終總結

    print("\n" + "🎯 "*40)
print("\n📊 你的實驗總結：")
print("\n" + "="*80)

if execution_times:
    print(f"\n✅ 已測試 {len(llms)} 個 LLM")
    fastest = min(execution_times, key=execution_times.get)
    slowest = max(execution_times, key=execution_times.get)
    print(f"   • 最快：{fastest} ({execution_times[fastest]:.2f}s)")
    print(f"   • 最慢：{slowest} ({execution_times[slowest]:.2f}s)")
    print(f"   • 平均：{sum(execution_times.values())/len(execution_times):.2f}s")

print(f"\n✅ 框架對比結論：")
print(f"   LangChain: 適合簡單應用、快速原型")
print(f"   LangGraph: 適合複雜工作流、多 Agent、多 LLM")

print(f"\n✅ 多 LLM 切換的好處：")
print(f"   • 成本優化：同一套代碼，根據任務選 LLM")
print(f"   • 供應商備份：一個 LLM 故障，自動切換")
print(f"   • 市場適應：新 LLM 出現，快速集成")

print(f"\n✅ 給個人公司的建議：")
print(f"   Year 1: 用 Claude SDK，多做項目（現金流優先）")
print(f"   Year 2: 評估 LangGraph，學習投入（複雜項目有收益）")
print(f"   Year 3: 成為專家，多 LLM 支持（競爭優勢）")

print("\n" + "="*80)
print(f"\n🚀 下一步行動：")
print(f"   1. 根據你的 POC 找到具體的 TA（目標客戶）")
print(f"   2. 驗證市場需求（beta 用戶反饋）")
print(f"   3. 決定是否投資 LangGraph 學習")
print(f"   4. 考慮多 LLM 支持（如果客戶有需求）")

print(f"\n" + "🎯 "*40)

    快速開始指南

    🎯 5 分鐘快速開始

    # 1. 安裝依賴
pip install jupyter notebook

# 2. 創建 .env 文件
cat > .env << EOF
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxx
GOOGLE_API_KEY=xxxxxxxxxxxx
EOF

# 3. 創建 Jupyter Notebook
jupyter notebook

# 4. 在 Notebook 中粘貼上面的代碼
# 5. 依次執行 Cells

    🔑 API Keys 獲取

    📋 Notebook 執行順序

    1. ✅ Cell 1：安裝依賴 2. ✅ Cell 2：配置 API Keys 3. ✅ Cell 3：初始化 LLM 4. ✅ Cell 4-5：對比測試 5. ✅ Cell 6：質量分析 6. ✅ Cell 7：LangGraph 演示 7. ✅ Cell 8：成本對比 8. ✅ Cell 9：框架對比 9. ✅ Cell 10：總結

    最終決策框架

    三位一體：老闆 × 顧問 × PM

    你同時是三個身份，優先級根據情況變化：

情況 1：現金流緊張（< 1 月）
優先級：老闆 > PM > 顧問
決策：快速賺錢最重要
  ├─ 用 Claude SDK（快）
  ├─ 多做小項目
  └─ 不學新框架

情況 2：穩定現金流（3+ 月）
優先級：顧問 > PM > 老闆
決策：給客戶好方案，建立品牌
  ├─ 評估 LangGraph（複雜項目）
  ├─ 提高服務質量
  └─ 長期客戶關係

情況 3：複雜項目 + 預算充足
優先級：PM > 顧問 > 老闆
決策：交付成功最重要
  ├─ 用 LangGraph（管理複雜度）
  ├─ 投前期設計時間
  └─ 降低風險

    快速決策矩陣

    ╔═══════════════════════════════════════════════════════════════╗
║                 你應該選哪個框架？                           ║
╠═══════════════════════════════════════════════════════════════╣

1. 項目複雜度？
   ├─ 簡單（1-2 Agent）→ 看 Q3
   ├─ 中等（3-5 Agent）→ 看 Q3
   └─ 複雜（5+ Agent 或並行）→ LangGraph ✓

2. 多 LLM 需求？
   ├─ 不需要 → 用官方 SDK
   └─ 需要 → 加 LangGraph

3. 時間線？
   ├─ < 2 周 → Claude SDK（快）
   ├─ 2-4 周 → LangChain（平衡）
   └─ > 1 月 → LangGraph（品質優先）

4. 團隊規模？
   ├─ 1-2 人 → Claude SDK（簡單）
   ├─ 3-5 人 → LangGraph（標準化）
   └─ 10+ 人 → LangGraph（可複用）

5. 長期規劃？
   ├─ 1 個項目 → Claude SDK（不值得學）
   ├─ 2-3 個 → 考慮 LangGraph
   └─ 5+ 個 → 必須 LangGraph（ROI 高）

╠═══════════════════════════════════════════════════════════════╣

最終建議：

✅ 用 Claude SDK 的條件：
   • 簡單應用（< 3 Agent）
   • 時間緊張（< 2 周）
   • 團隊小（1-2 人）
   • 短期項目（< 1 個項目規劃）

✅ 用 LangChain 的條件：
   • 快速原型
   • 簡單應用
   • 想支持多 LLM（但工作流簡單）
   • 喜歡靈活性

✅ 用 LangGraph 的條件：
   • 複雜工作流（> 3 Agent）
   • 並行執行或分支邏輯
   • 多 LLM 支持
   • 長期項目規劃（3+ 個）
   • 團隊 > 3 人

╚═══════════════════════════════════════════════════════════════╝

    核心結論

    1. 框架選擇不是技術問題，是商業問題
   ✓ 有付費客戶？有複雜項目？有長期規劃？
   ✗ 這些都沒有？先驗證市場

2. LangGraph 的價值在於「長期」
   • 第 1 個項目：LangGraph 可能慢
   • 第 3 個項目：LangGraph 快 50%
   • 第 5 個項目：LangGraph 快 70%

3. 多 LLM 不是為了省錢，而是為了自由
   • 供應商備份（可用性）
   • 成本優化（可選）
   • 市場適應（長期）

4. POC 階段最重要的是市場驗證，不是技術選擇
   • 1 周市場反饋 > 2 周完美代碼
   • TA 決定一切
   • 框架是後話

5. 個人公司的出路是「垂直深化」，不是「技術秀肌肉」
   • 某個領域的專家 > 全能技術人
   • $10k-20k 的垂直項目 > $2k-5k 的通用項目
   • 品質溢價 > 技術先進性

    後記

    **給你的最後話**：

    你已經掌握了 Claude Agent SDK，這給了你第一步的優勢。現在的問題不是「選哪個框架」，而是「選哪個市場」。

    LangChain/LangGraph 是在你確定市場和客戶後，為了「長期優化」的選擇。不是「先進」，而是「務實」。

    現在就出去找 TA，快速驗證想法。3 個月後，當你有 3-5 個清晰的客戶需求時，再回過頭來考慮技術選擇。那時候的決策會基於真實數據，而不是假設。

    同時，寫好你的博客。「Claude Agent SDK 深度實踐指南」會成為你的品牌。未來的「LangGraph 多 LLM 架構指南」會是補充。

    競爭力不來自「最新技術」，而來自「解決真實問題的深度」。

    **撰寫時間**：2026-03-17 **版本**：1.0 **包含**：完整分析 + Jupyter Notebook + 決策框架

    **加油！👊**

  • Agent Team 多輪迭代：從失敗到成功的設計演進

    Document Status: Living Document (持續更新)
    Last Updated: 2026-03-17
    Author: Claude Code + Tom
    Purpose: 從 SimpleEC OMS 多次失敗的 Agent Team 經驗中提煉最佳實踐

    🎯 重點摘要

    • 問題：4 次 Agent Team 啟動都在 24+ 小時後卡住，根本原因不在代碼，而在設計與 Prompt
    • 核心原則：編碼依賴（Task.blockedBy/blocks）、明確停止條件、2 小時 timeout、結構化交付物
    • 關鍵對比：Provider Chain (複雜) vs Sequential Phase (簡單) — 後者減少隱式依賴、自動強制約束
    • Prompt 檢查清單：5 大維度、17 項細節檢查，防止 Agent 卡住或無限期等待
    • 成功設計：明確的時間表、具體的交付物格式 (JSON)、禁止行為列表、協調者角色

    序言：為什麼我們一直失敗

    從 2026-03-03 到 2026-03-17，我們嘗試啟動過至少 4 個 Agent Team，每一次都卡住 24+ 小時：

    1. simpleec-oms-audit (3/3) — 任務分配錯亂，Agent 互相等待
    2. simpleec-oms-bidirectional-audit (3/10) — 複雜的雙向驗證設計，Agent 不知道什麼時候應該停止
    3. simpleec-oms-quality-audit (3/16) — Task 被分配給錯誤的 Agent，導致 3 個 Agent 空轉 24 小時

    根本原因不在代碼，而在於：

    • ❌ 設計太複雜，隱式依賴沒有編碼
    • ❌ Prompt 寫得不清楚，Agent 不知道什麼時候應該停止或等待
    • ❌ 沒有 Timeout 機制，導致無限期等待
    • ❌ 任務分配邏輯複雜，容易出錯
    • ❌ Agent 沒有明確的”停止條件”，導致亂工作或空轉

    本文將詳細解析這些問題，並提供可複製的最佳實踐。

    🎯 你需要打什麼讓我一步到位

    複製以下內容給 Claude

    我要啟動 Agent Team 做 [你的任務]

系統：[系統名]
檢查維度：[A], [B], [C]
時間：[時間限制]
Agent：[N 個]

創建：TEAM_PLAN.md / AGENT_PROMPTS.md / CHECKLIST.md / settings.json

    📋 成功的 Prompt 範本

    You are ARCHITECT on [TEAM_NAME].

Verify [SYSTEM]:
- [Check A]
- [Check B]

DELIVERABLE (JSON):
{ "task_id": 1, "findings": { "score": X, "ready": true } }

BEGIN PHASE 1 NOW.

    第一部分：為什麼 Agent Team 會卡住？

    原因 1：複雜的隱式依賴

    ❌ 壞設計示例：使用 Provider Chain + Consumer Chain 雙向驗證（複雜且失敗）。有 4 個同步點，但都是文字描述，沒有編碼到 Task 系統。Task 之間的依賴關係是隱式的（”Task #1 完成後才能開始 Task #2″，但沒有在 blockedBy 里標記）。Agent 不知道應該等待誰或被誰等待。

    後果：當任務分配出錯（比如 Task #2 被分給了錯誤的 Agent），整個鏈條斷裂。Architect 和 Backend-QA 無所事事，空轉 24+ 小時，持續消耗內存。

    原因 2：Prompt 寫得不清楚 → Agent 不知道什麼時候該停止

    Prompt 缺少明確的停止條件。完成 Task #1 後，Agent 不知道應該做什麼——是否應該主動聯繫其他 Agent？是否應該重新檢查自己的工作？內存會持續增長（因為 Agent 一直在運行）。

    實際情況：Architect 完成 Task #1 後，發現沒有 Task #2 和 #3 的結果（因為被分配錯了）。開始懷疑，重新讀一遍所有文件。14 小時後，內存從 380MB 漲到 440MB。最後 OOM → 系統當機。

    原因 3：沒有 Timeout 機制

    舊設計 新設計
    ❌ Agent Task 超時限制：無
    → 可以無限期等待
    → 可以無限期工作
    → 內存持續增長，最終 OOM    		 ✅ Agent Task 超時限制：2 小時
    → 2 小時後，自動標記 timeout
    → 解鎖下一個任務或停止
    → 即使出錯，也不會無限期卡住

    原因 4：Agent 之間沒有同步點

    舊設計中，Task #1 在工作，Task #2 也在工作，但 Task #2 應該等待 Task #1。沒人告訴他們應該等待誰。新設計中，用 Task.blockedBy = [1, 2] 明確表示”我要等 Task #1, #2″。

    第二部分：好的 Agent Team 設計原則

    原則 1：Show, Don’t Tell（編碼依賴，不要寫文字）

    為什麼？ Task 系統會自動強制依賴順序，不會分配錯誤。不依賴人工判斷。系統可以自動檢測循環依賴或孤立任務。

    原則 2：一個 Agent 做一件事

    ❌ 壞：Task #2 包含 3 個不同的東西（Schema 驗證、Kafka 驗證、Handler 驗證）。Agent 容易分心，難以判斷什麼時候”完成”。

    ✅ 好：Task #2 目標清晰：”驗證數據層能否支持 API 承諾”。包含 3 個驗證點，但都是同一件事的一部分。交付物是一個結構化的 JSON 對象。

    原則 3：明確的交付物結構

    ❌ 壞：”Generate audit report with Executive summary, Critical issues list…” 模糊，無法驗證是否合格。

    ✅ 好：返回結構化 JSON，包含量化指標（alignment score）、布爾標誌（ready_for_next_phase）、具體問題列表。下一個 Agent 可以用 JSON parser 讀取。

    原則 4：Prompt 要明確定義”停止條件”

    Prompt 必須明確說：完成 Task 後，Agent 應該做什麼（答案是：停止工作，等待通知）。沒有”循環工作”的空間。明確的等待機制（team-lead 會告訴你什麼時候開始下一個 Phase）。

    原則 5：Timeout 是必需的

    新設計：2 小時 timeout。時間到了，自動標記 timeout。自動解鎖下一個 Task（即使當前 Task 沒完成）。自動通知 team-lead。防止無限期等待。

    第三部分：Prompt 編寫終極檢查清單

    A. 責任清晰度（Clarity of Responsibility）

    • ✅ 一個 Agent，一件事 — 避免重載式任務設計
    • ✅ 目標可測 — 不是”驗證 schema 完整性”，而是”生成 JSON with schema_integrity score”
    • ✅ 交付物明確 — 結構化 JSON，而不是自由文本報告

    B. 停止條件明確（Clear Stop Conditions）

    • ✅ Prompt 明確說什麼時候應該停止 — “After Task #1 is complete, do NOT continue. Wait for team-lead notification.”
    • ✅ 沒有”循環工作”的空間 — “After generating findings JSON, stop. Do not re-read files.”
    • ✅ 明確的等待機制 — “Wait for team-lead message: ‘Phase 2 begins’”

    C. 依賴關係編碼（Dependency Encoding）

    • ✅ Task.blockedBy 明確填寫 — "blockedBy": [1] 表示”我等 Task #1″
    • ✅ Task.blocks 明確填寫 — "blocks": [3, 4] 表示”我阻擋 Task #3 和 #4″
    • ✅ 沒有循環依賴 — Task #1 blocks #2, #2 blocks #3, #3 blocks #1 ← 循環！

    D. 超時保護（Timeout Protection）

    • ✅ Prompt 中明確提到超時時間 — “You have 2 hours to complete Task #1”
    • ✅ 告訴 Agent 超時時會發生什麼 — “If 2 hours pass, next phase will begin regardless”
    • ✅ Timeout 不應該導致錯誤，只是解鎖 — 後自動繼續下一階段

    E. Agent 之間的協調（Inter-Agent Coordination）

    • ✅ 明確說是否應該主動聯繫其他 Agent — “Do NOT contact backend-qa or frontend-qa”
    • ✅ 明確說如何接收通知 — “You will receive explicit notification from team-lead when Phase 2 begins”
    • ✅ 明確說何時應該報告問題 — “Report them in your findings JSON. Do NOT try to fix them yourself.”

    第四部分：Prompt 好與壞的完整對比

    ❌ 壞 Prompt（導致失敗）

    缺少：明確的完成後行為、明確的等待規則、Timeout 時間、停止條件、交付物格式的具體性。

    後果：Architect 完成 Task #1 後，發現沒有 Task #2 和 #3 的結果。不知道應該等待還是繼續工作。開始懷疑自己的分析，重新讀文件。持續讀文件和重新分析 14+ 小時。內存從 380MB 漲到 440MB。最後 OOM，系統當機。

    ✅ 好 Prompt（成功設計）

    特點：明確的時間表（0-2h Phase 1, 2-4h 等待, 4-6h Phase 4）。明確的停止條件（”完成後停止，不要做任何其他事”）。明確的交付物（結構化 JSON）。明確的等待機制（team-lead 會告訴你什麼時候開始 Phase 4）。明確的禁止行為（❌ 列出了不應該做的事）。

    後果：Architect 完成 Task #1。知道自己應該停止（Prompt 明確說了）。進入等待模式（不讀文件，不重新分析）。2 小時後，如果沒有 Task #4 通知，自動 timeout。內存穩定在 380MB（沒有持續增長）。系統正常運行。

    第五部分：常見錯誤與修正

    錯誤 1：Prompt 寫得太長和太複雜

    修正：用清晰的結構（Markdown headers）。用列表而不是段落。用例子而不是抽象描述。用”禁止行為”而不是”允許行為”。目標：500 字清晰 Prompt，而不是 2000 字複雜 Prompt。

    錯誤 2：隱式假設 Agent 會自己推斷

    ❌ 壞：”After Task #1, you will know when to start Task #2″（Agent 怎麼知道？沒人告訴他！）

    ✅ 好：”After Task #1, wait for team-lead message: ‘Task #2 begins’. Only then should you proceed.”

    錯誤 3：交付物格式模糊

    ❌ 壞：”Generate a report with findings”

    ✅ 好：生成 JSON，具有明確的字段結構 (status, findings, critical_issues 等)

    錯誤 4：沒有明確的超時時間

    ✅ 修正：Timeout: 2 hours — If 2 hours pass, your task is automatically marked timeout. Next phase will proceed regardless. You will be notified when your timeout occurs.

    第六部分：Agent Team 設計檢查清單

    Pre-Launch Checklist

    系統狀態：內存充足 (>8GB available)。沒有舊的 Agent Team 在運行。Task 目錄是空的。

    Task 設計：每個 Task 有明確的 id, subject, description。每個 Task 的 blockedBy 和 blocks 已填寫（沒有循環依賴）。沒有孤立的 Task。每個 Task 有 2 小時的隱式 timeout。

    Prompt 設計：每個 Agent 的 Prompt 有明確的責任（一件事）。每個 Prompt 有明確的停止條件。每個 Prompt 有具體的交付物格式（JSON）。每個 Prompt 有明確的等待機制。每個 Prompt 禁止了不應該做的事情（❌ 列表）。

    交付物定義：所有交付物都是結構化的（JSON）。每個交付物都有 status 字段。下一個 Agent 能解析上一個 Agent 的交付物。交付物不應該是自由文本，應該是結構化數據。

    同步機制：有明確的”team-lead”角色負責協調。有明確的通知機制。有明確的失敗恢復流程。沒有 Agent 之間的直接通信（都通過 team-lead）。

    Launch Checklist

    監控：每 30 分鐘檢查一次內存使用。監控是否有 Agent 卡住。準備好 2 小時後手動檢查 timeout 機制。

    信號：知道什麼樣的行為表示”卡住”（讀同一個文件超過 1 小時，內存持續增長 10% 以上，沒有進展 30 分鐘以上）。準備好應急措施（2 分鐘內關掉所有 Agent，清理內存，回滾到之前的狀態）。

    第七部分：迭代和改進

    本文將根據實驗結果進行迭代。每當我們啟動新的 Agent Team 時：

    1. 記錄過程 — 啟動時間、Agent 行為、完成時間、內存使用、任何卡住或異常情況
    2. 在本文中更新 — 如果發現新的問題、更好的 Prompt 寫法、或 Timeout 時間不合適的情況
    3. 版本控制 — 每次大的更新，提升版本號。在文件頂部記錄更新日期和內容

    總結

    從失敗中學到的核心真理：

    1. 設計要簡單，依賴要明確 — 不要用複雜的 Provider Chain，用簡單的 Sequential Phase
    2. 編碼依賴，不要寫文字 — blockedBy 和 blocks 必須填寫，隱式依賴是毒藥
    3. Prompt 要明確停止條件 — Agent 必須知道什麼時候應該停止
    4. Timeout 是必需的保險 — 沒有 timeout，Agent 可以無限期卡住
    5. 交付物要結構化 — JSON 而不是自由文本，下一個 Agent 能解析
    6. 有一個協調者（team-lead） — 不要讓 Agent 之間直接通信

    下一步：用 v2 設計啟動 Quality Audit Team。記錄過程和結果。根據結果更新本文。建立標準範本（Task 和 Prompt 的 template）。

    實施深度：v3 計畫的四層架構

    前面的原則是設計哲學。但實際部署 v3 計畫時，我們加入了四項關鍵實施細節，把抽象的原則轉換為可監控、可恢復、可自動化的運作。

    ①分層監控架構（Team-lead 的心跳）

    v3 計畫引入了 Team-lead 監控層，專職於此，间隔嚴格：30秒 Session 健康檢查、30分鐘超時檢查、60分鐘進度報告、5分鐘內存監控。

    ②事件驅動協調（4 個事件）

    v3 計畫改為事件驅動模型，完全由 Team-lead 控制狀態轉遷。4個事件：Task#1完成→解鎖Task#2&3、Task#2&3都完成→通知Architect進行Task#4、Task#4完成→生成報告。

    ③應急與恢復（5 個故障模式）

    v3 計畫為5種情況預先定義恢復策略：Orphaned Agents(中止審計)、Multiple Timeouts(部分報告)、Invalid JSON(記錄錯誤繼續)、OOM Event(強制超時解鎖)、Stalled Task(檢測重啟或強制超時)。

    ④完整實現範例

    完整的Task生命週期：t=0初始化、t=0-30分鐘Architect驗證、t=25觸發Event1解鎖Task#2&3、t=25-50並行執行QA驗證、t=50觸發Event2&3通知Architect、t=50-110Task#4最終驗證、t=115報告生成完成。總耗時115分鐘，4個Agent共消耗1.8GB內存。

    v3 計畫 vs v2：7 個關鍵改進

    依賴編碼從文字敘述改為JSON(blockedBy/blocks)、停止條件從暗示改為明確、超時機制從提到改為實現(120min+30min+自動unlock)、監控從無改為Team-lead 30秒心跳、協調從Agent間通信改為Team-lead主控、交付物從文字改為JSON schema、故障恢復從無預案改為5個策略。

    「後即時」監控與自動恢復

    v3 計畫的終極目標是達到「後即時(Near Real-Time)監控」：不是等Task失敗才發現，而是任何異常2分鐘內自動檢測並響應。解決之前24小時卡住的問題。